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About ILE C/C++ for iSeries Run-time Library Functions 


(SC41-5607) 


This book provides reference information about: 
* Include files 

* Run-time functions 

* Run-time considerations 


Use this book as a reference when you write Integrated Language Environment 
(ILE) C applications. 


This book does not describe how to program in the C programming language or 
explain the concepts of ILE. Companion publications for this reference are: 


* ILE C for AS/400 Language Reference 

* WebSphere Development Studio: ILE C/C++ Programmer's Guide 
° ILE Concepts 

° ILE C/C++ for AS/400 MI Library Reference 


For information about other ILE C publications, see the iSeries Information Center 
at http://www.ibm.com/eserver /iseries /infocenter. 


For a list of related publications, see 


Who should read this book 


This book is intended for programmers who are familiar with the C programming 
language and who want to write or maintain ILE C applications. You must have 
experience in using applicable iSeries menus, and displays or control language 
(CL) commands. You also need knowledge of Integrated Language Environment as 
explained in the ILE Concepts manual. 


A note about examples 


The examples in this book that illustrate the use of library functions are written in 
a simple style. The examples do not demonstrate all possible uses of C language 
constructs. Some examples are only code fragments and do not compile without 
additional code. 


All complete runnable examples for library functions and machine interface 
instructions are in library QCPPLE, in source file QACSRC. Each example name is 
the same as the function name or instruction name. For example, the source code 
for the example illustrating the use of the _Rcommit() function in this book is in 
library QCPPLE, file QACSRC, member RCOMMIT. The QSYSINC library must be 
installed. 


iSeries Navigator 


iSeries Navigator is a powerful graphical interface for Windows clients. With 
iSeries Navigator, you can manage and administer your iSeries systems from your 
Windows desktop. 
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You can use iSeries Navigator to manage communications, printing, database, 
security, and other system operations. iSeries Navigator includes Management 
Central for managing multiple iSeries systems centrally. 


Eigure 1] shows an example of the iSeries Navigator display: 
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File Edit View Options Help 
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Figure 1. iSeries Navigator Display 


This new interface has been designed to make you more productive and is the 
only user interface to new, advanced features of OS/400. Therefore, IBM 
recommends that you use iSeries Navigator, which has online help to guide you. 
While this interface is being developed, you may still need to use a traditional 
emulator such as PC5250 to do some of your tasks. 


Installing iSeries Navigator 


To use iSeries Navigator, you must have iSeries Access installed on your Windows 
PC. For help in connecting your Windows PC to your iSeries system, consult iSeries 
Access for Windows--Setup, SC41-5507-03. 


iSeries Navigator is a separately installable component of iSeries Access that 
contains many subcomponents. If you are installing for the first time and you use 
the Typical installation option, the following options are installed by default: 


* iSeries Navigator base support 
* Basic operations (messages, printer output, and printers) 


To select the subcomponents that you want to install, select the Custom installation 
option. (After iSeries Navigator has been installed, you can add subcomponents by 
using iSeries Access Selective Setup.) 


1. Display the list of currently installed subcomponents in the Component 
Selection window of Custom installation or Selective Setup. 


2. Select iSeries Navigator. 
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3. Select any additional subcomponents that you want to install and continue with 
Custom installation or Selective Setup. 


After you install iSeries Access, double-click the iSeries Navigator icon on your 
desktop to access iSeries Navigator and create an iSeries connection. 


Prerequisite and related information 


Use the iSeries Information Center as your starting point for looking up iSeries 
technical information. 


You can access the Information Center two ways: 
* From the following Web site: 
http://www. ibm.com/eserver/iseries/infocenter 
* From CD-ROMs that ship with your Operating System/400 order: 


iSeries Information Center, SK3T-4091-02. This package also includes the PDF 
versions of iSeries manuals, iSeries Information Center: Supplemental Manuals, 
SK3T-4092-01, which replaces the Softcopy Library CD-ROM. 


The iSeries Information Center contains advisors and important topics such as 
Java, TCP/IP, Web serving, secured networks, logical partitions, clustering, CL 
commands, and system application programming interfaces (APIs). It also includes 
links to related IBM Redbooks and Internet links to other IBM Web sites such as 
the Technical Studio and the IBM home page. 


With every new hardware order, you receive the iSeries Setup and Operations 
CD-ROM, SK3T-4098-01. This CD-ROM contains IBM @server iSeries Access for 
Windows and the EZ-Setup wizard. iSeries Access offers a powerful set of client 
and server capabilities for connecting PCs to iSeries servers. The EZ-Setup wizard 
automates many of the iSeries setup tasks. 


For other related information, see the 


How to send your comments 


Your feedback is important in helping to provide the most accurate and 
high-quality information. If you have any comments about this book or any other 
iSeries documentation, fill out the readers’ comment form at the back of this book. 


* If you prefer to send comments by mail, use the readers’ comment form with the 
address that is printed on the back. If you are mailing a readers’ comment form 
from a country other than the United States, you can give the form to the local 
IBM branch office or IBM representative for postage-paid mailing. 


* If you prefer to send comments by FAX, use either of the following numbers: 
— United States and Canada: 1-800-937-3430 
— Other countries: 1-507-253-5192 
* If you prefer to send comments electronically, use one of these e-mail addresses: 
— Comments on books: 
RCHCLERK@us.ibm.com 
IBMMAIL, to IBMMAIL(USIB56RZ) 
— Comments on the iSeries Information Center: 
RCHINFOC@us.ibm.com 


Be sure to include the following: 


About ILE C/C++ for iSeries Run-time Library Functions (SC41-5607) xi 


* The name of the book. 
* The publication number of the book. 
* The page number or topic to which your comment applies. 


xii ILEC /C++ for iSeries Run-Time Library Functions V5R2 
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Chapter 1. Include Files 


The include files that are provided with the run time library contain macro and 
constant definitions, type definitions, and function declarations. Some functions 
require definitions and declarations from include files to work properly. The 
inclusion of files is optional, as long as the necessary statements from the files are 
coded directly into the source. 


This section describes each include file, explains its contents, and lists the functions 
that are declared in the file. 


The QSYSINC (system openness includes) library must be installed on your iSeries 
system. QSYSINC contains include files useful for C users, such as system API, 
Dynamic Screen Manager (DSM), and LE header files. The QSYSINC library 
contains header files that include the prototypes and templates for the MI built-ins 
and the ILE C MI functions. See the ILE C/C++ for AS/400 MI Library Reference for 
more information about these header files. 


<assert.h> 


The <assert.h> include file defines the fssertl macro. You must include assert.h 
when you use assert. 


The definition of assert is in an #ifndef preprocessor block. If you have not 
defined the identifier NDEBUG through a #define directive or on the compilation 
command, the assert macro tests the assertion expression. If the assertion is false, 
the system prints a message to stderr, and raises an abort signal for the program. 
The system also does a Dump Job (DMPJOB) OUTPUT(*PRINT) when the 
assertion is false. 


If NDEBUG is defined, assert is defined to do nothing. You can suppress program 
assertions by defining NDEBUG. 


<ctype.h> 
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The <ctype.h> include file defines functions that are used in character 
classification. The functions that are defined in <ctype.h> are: 


Note: ' These functions are available with SYSIFCOPT(*IFSIO) AND 
LOCALETYPE(*LOCALE) or LOCALETYPE(##7LOCALEUCS2) are 
specified on the compilation command. 

Note: 7 This function is applicable to C++ only. 


<decimal.h> 


The <decimal.h> include file contains definitions of constants that specify the 
ranges of the packed decimal type and its attributes. The <decimal.h> file must be 
included with a #include directive in your source code if you use the keywords 
decimal, digitsof, or precisionof. 


<errno.h> 


The <errno.h> include file defines macros that are set to the errno variable. The 
<errno.h> include file defines macros for values that are used for error reporting 
in the C library functions and defines the macro errno. An integer value can be 
assigned to errno, and its value can be tested during run time. See "Checking the 
Errno Value" in the WebSphere Development Studio: ILE C/C++ Programmer’s Guide 
for information about displaying the current errno value. 


Note: To test the value of errno after library function calls, set it to 0 before the 
call because its value may not be reset during the call. 


<except.h> 


The <except.h> include file declares types and macros that are used in ILE C 
exception handling. 


The definition of .INTRPT_Hndlr_Parms_T is: 


typedef Packed struct { 


unsigned int 


Block_Size; 


_INVFLAGS_T Tgt_Flags; 

char reserved[8] ; 

_INVPTR Target; 

_INVPTR Source; 

_SPCPTR Com_Area; 

char Compare_Data[32]; 

char Msg_Id[7]; 

char reserved]; 
INTRPT_Mask_T Mask; 


unsigned int 
unsigned short 
unsigned short 
char 


Msg_Ref_Key; 
Exception_Id; 
Compare_Data_Len; 
Signal Class; 


char Priority; 

short Severity; 

char reserved3[4]; 

int Msg_Data_Len; 
char Mch_Dep_Data[10]; 
char Tgt_Inv_Type; 
_SUSPENDPTR Tgt_Suspend; 

char Ex_Data[48]; 


} _INTRPT_Hnd1r_Parms_T; 


Element 


Description 


Block_Size 


The size of the parameter block passed to the exception handler. 


Tgt_Flags 


Contains flags that are used by the system. 


reserved 


An eight byte reserved field. 
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Target An invocation pointer to the call stack entry that enabled the exception 
handler. 


Source 
An invocation pointer to the call stack entry that caused the exception. If 
that call stack entry no longer exists, then this is a pointer to the call stack 
entry where control resumes when the exception is handled. 


Com_Area 
A pointer to the communications area variable specified as the second 
parameter on the #pragma exception_handler. If a communication area was 
not specified, this value is NULL. 


Compare_Data 
The compare data consists of 4 bytes of message prefix, for example CPF, 
MCH, followed by 28 bytes which are taken from the message data of the 
related message. In the case where the message data is greater than 28 
these are the first 28 bytes. For MCH messages, these are the first 28 bytes 
of the exception related data that is returned by the system (substitution 
text). 


Msg_Id 
A message identifier, for example CPF123D. *STATUS message types are 
not updated in this field. 


reserved1 
A 1 byte pad. 


Mask This is an 8-byte exception mask, identifying the type of the exception that 


occurred, for example a decimal data error. The possible types are shown 
in [able 20 on ee 46 l. 


Msg_Ref_Key 
A key used to uniquely identify the message. 


Exception_Id 
Binary value of the exception id, for example, 0x123D. To display value, 
use conversion specifier %x as information is stored in hex value. 


Compare_Data_Len 
The length of the compare data. 


Signal_Class 
Internal signal class. 


Priority 
The handler priority. 


Severity 
The message severity. 


reserved3 
A four-byte reserved field. 


Msg_Data_Len 
The length of available message data. 


Mch_Dep_Data 
Machine-dependent data. 


Tgt_Inv_Type 
Invocation type. Macros are defined in <mimchobs.h>. 
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Tgt_Suspend 
Suspend pointer of the target. 


Ex_Data 
The first 48 bytes of exception data. 


The definition of _CNL_Hndlr_Parms_T is: 


typedef Packed struct { 
unsigned int Block_Size; 
_INVFLAGS_T Inv_Flags; 


char reserved[8] ; 
_INVPTR Invocation; 
_SPCPTR Com_Area; 


_CNL_Mask_T Mask; 
} _CNL_Hnd1r_Parms_T; 


Element 
Description 


Block_Size 
The size of the parameter block passed to the cancel handler. 


Inv_Flags 
Contains flags that are used by the system. 


reserved 
An eight byte reserved field. 


Invocation 
An invocation pointer to the invocation that is being cancelled. 


Com_Area 
A pointer to the handler communications area defined by the cancel 
handler. 


Mask A 4 byte value indicating the cancel reason. 


The following built-ins are defined in <except.h>: 


Built-in 
Description 


__EXBDY 
The purpose of the _ EXBDY built-in or _EXBDY macro is to act as a 
boundary for exception-sensitive operations. An exception-sensitive 
operation is one that may signal an exception. An EXBDY enables 
programmers to selectively suppress optimizations that do code motion. 
For example, a divide is an exception-sensitive operation because it can 
signal a divide-by-zero. An execution path containing both an EXBDY and 
a divide will perform the two in the same order with or without 
optimization. For example: 


b = expl; 
Cc = exp2; 
“EXBDY(); 
a = b/c; 
__VBDY 


The purpose of a __VBDY built-in or _VBDY macro is to ensure the home 
storage locations are current for variables that are potentially used on 
exception paths. This ensures the visibility of the current values of 
variables in exception handlers. A VBDY enables programmers to 
selectively suppress optimizations, such as redundant store elimination and 
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forward store motion to enforce sequential consistency of variable updates. 
In the following example, the VBDYs ensure that state is in it’s home 
storage location before each block of code that may signal an exception. A 
VBDY is often used in combination with an EXBDY to ensure that earlier 
assignments to state variables really update home storage locations and 
that later exception sensitive operations are not moved before these 
assignments. 

state = 1; 

_VBDY () 3 

/* Do stuff that may signal an exception. */ 

state = 2; 

_VBDY () 3 

/* More stuff that may signal an exception. */ 
state = 3; 
_VBDY(); 


For more information on built-ins, see the ILE C/C++ for AS/400 MI Library 
Reference . 


<float.h> 
The <float.h> include file defines constants that specify the ranges of 
floating-point data types. For example, the maximum number of digits for objects 
of type double or the minimum exponent for objects of type float. 
<langinfo.h> 
The <langinfo.h> include file contains the declarations and definitions that are 
used by nl_langinfo. 
<limits.h> 
The <limits.h> include file defines constants that specify the ranges of integer and 
character data types. For example, the maximum value for an object of type char. 
<locale.h> 


The <lo 


cale.h> include file declares the ketlocale()] and [Localeconv()| library 


functions. These functions are useful for changing the C locale when you are 


creating applications for international markets. 
The <locale.h> include file also declares the type struct lconv and the following 
macro definitions: 
NULL LC_ALL LG_e* LC_C_FRANCE  LC_UCS2_ALL * 
1 

LC_C_GERMANY LC_C_ITALY ' LC_C_SPAIN' LC_C_UK’ LC_UCS2_CTYPE* 
1 
LC_C_USA ! LC_COLLATE LC_CTYPE LC_MESSAGES ? LC_UCS2_COLLATE? 
LC_TOD LC_MONETARY LC_NUMERIC — LC_TIME 
Note: ' This macro is defined only when LOCALETYPE(*CLD) or 

LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 
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? This macro is defined only when LOCALETYPE(*LOCALE) is specified on 
the compilation command. 


3 This macro is defined only when LOCALETYPE(*LOCALEUCS2) is 
specified on the compilation command. 


<math.h> 


The <math.h> include file declares all the floating-point math functions: 


kos flod 
east lEmod) tad 


bcos] 
bsid 
btanl lfrexd hoddl 
s f & & 
keill ae Kind 


J 


Note: The Bessel functions are a group of functions named j0, jl, jn, yO, yl, 
and yn. 


ny 


Note: Floating point numbers are only guaranteed 15 significant digits. This 
can greatly affect expected results if multiple floating point numbers are 
used in a calculation. 


<math.h> defines the macro HUGE_VAL, which expands to a positive double 
expression, and possibly to infinity on systems that support infinity. 


For all mathematical functions, a domain error occurs when an input argument is 
outside the range of values that are allowed for that function. In the event of a 
domain error, errno is set to the value of EDOM. 


A range error occurs if the result of the function cannot be represented in a double 
value. If the magnitude of the result is too large (overflow), the function returns 
the positive or negative value of the macro HUGE_VAL, and sets errno to 
ERANGE. If the result is too small (underflow), the function returns zero. 


| <mallocinfo.h> 


Include file with _C_TS_malloc_info and _C_TS_malloc_debug. 


<monetary.h> 


The <monetary.h> header file contains declarations and definitions that are related 
to the output of monetary quantities. These declarations and definitions are 
accessible only when LOCALETYPE(*LOCALE) or LOCALETYPE(*7LOCALEUCS2) 
is specified on the compilation command. 
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<nl_types.h> 


The <nl_types.h> header file contains catalog definitions. These definitions are 
accessible only when SYSIFCOPT(*IFSIO) with either LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


<pointer.h> 
The <pointer.h> include file contains typedefs and pragma directives for the 
iSeries pointer types: space pointer, open pointer, invocation pointer, label pointer, 
system pointer, and suspend pointer. The typedefs _ANYPTR and _SPCPTRCN are 
also defined in <pointer.h>. 

<recio.h> 


The <recio.h> include file defines the types and macros, and prototypes functions 
for all the ILE C record input and output (I/O) operations. 


The following functions are defined in <recio.h>: 


_Racquire _Rclose _Rcommit _Rdelete 
_Rdevatr _Rfeod _Rfeov _Rformat 
_Rindara _Riofbk _Rlocate _Ropen 
_Ropnfbk _Rpgmdev _Rreadd _Rreadf 
_Rreadindv _Rreadk _Rreadl _Rreadn 
_Rreadnc _Rreadp _Rreads _Rrelease 
_Rrlslck _Rrollbck _Rupdate _Rupfb 
_Rwrite _Rwrited _Rwriterd _Rwrread 
The following positioning macros are defined in recio.h: 

__END __END_FRC __ FIRST __KEY_EQ 
__KEY_ GE __KEY GT __KEY_LE __KEY LT 
__KEY_NEXTEQ __ KEY NEXTUNQ __KEY_PREVEQ __KEY_PREVUNQ 
__KEY_ LAST __KEY_NEXT __NO_POSITION __ PREVIOUS 
__ PRIOR __RRN_EQ __ START __START_FRC 
__LAST __NEXT 


The following macros are defined in recio.h: 


__DATA_ONLY __DFT __NO_LOCK __NULL_KEY_MAP 


The following directional macros are defined in recio.h: 


__READ_NEXT __READ_PREV 


The following functions and macros support locate or move mode: 


_Rreadd _Rreadf _Rreadindv _Rreadk 
_Rreadl _Rreadn _Rreadnc _Rreadp 
_Rreads _Rupdate _Rwrite _Rwrited 
_Rwriterd _Rwrread 
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Any of the record I/O functions that include a buffer parameter may work in 
move mode or locate mode. In move mode, data is moved between the user 
user-supplied buffer and the system buffer. In locate mode, the user must access 
the data in the system buffer. Pointers to the system buffers are exposed in the 
_RFILE structure. To specify that locate mode is being used, the buffer parameter 
of the record I/O function is coded as NULL. 


A number of the functions include a size parameter. For move mode, this is the 
number of data bytes that are copied between the user-supplied buffer and the 
system buffer. All of the record I/O functions work with one record at a time 
regardless of the size that is specified. The size of this record is defined by the file 
description. It may not be equal to the size parameter that is specified by the user 
on the call to the record I/O functions. The amount of data that is moved between 
buffers is equal to the record length of the current record format or specified 
minimum size, whichever is smaller. The size parameter is ignored for locate 
mode. 


The following types are defined in recio.h: 


Information for controlling opened record I/O operations 


typedef Packed struct { 
char reserved1[16] ; 
volatile void *const *const in_buf; 
volatile void *const *const out_buf; 


char reserved2 [48] ; 
_RIOFB_T riofb; 
char reserved3[32]; 
const unsigned int buf_length; 
char reserved4[28] ; 
volatile char *const in_null_map; 
volatile char *const out_null_map; 
volatile char ~*const null_key_map; 
char reserved5 [48] ; 
const int min_length; 
short null_map_len; 
short null_key_map_len; 
char reserved6[8] ; 
}_RFILE; 
Element 
Description 


in_null_map 
Specifies which fields are to be considered NULL when you read from a 
database file. 


out_null_map 
Specifies which fields are to be considered NULL when you write to a 
database file. 


null_key_map 
Specifies which fields contain NULL if you are reading a database by key. 


null_map_len 
Specifies the lengths of the in_null_map and out_null_map. 


null_key_map_len 
Specifies the length of the null_key_map. 


Record I/O Feedback Information 
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typedef struct { 


unsigned char *key; 
_Sys_Struct_T *Sysparm; 
unsigned long rrn; 
long num_bytes; 
short blk_count; 
char blk_filled_by; 
int dup_key os 
int icf_locate :1; 
int reservedl :6; 
char reserved2[20] ; 
}_RIOFB_T; 
Element 
Description 


key If you are processing a file using a keyed sequence access path, this field 
contains a pointer to the key value of the record successfully positioned to, 
read or written. 


sysparm 
This field is a pointer to the major and minor return code for ICF, display, 
and printer files. 


mm This field contains the relative record number of the record that was 
successfully positioned to, read or written. 


num_bytes 
This field contains the number of bytes that are read or are written. 


blk_count 
This field contains the number of records that remain in the block. If the 
file is open for input, blkrcd=y is specified, and a read function is called, 
this field will be updated with the number of records remaining in the 
block. 


blk_filled_by 
This field indicates the operation that filled the block. If the file is open for 
input, blkrcd=y is specified, and a read function is called. This field will be 
set to the _ READ_NEXT macro if the _Rreadn function filled the block or 
to the _ READ_PREV macro if the _Rreadp function filled the block. 


System—Specific Information 
typedef struct { 


void *sySparm_ext; 
_Maj_Min_rc_T _Maj_Min; 
char reserved1[12] ; 


} _Sys Struct_T; 


Major and Minor Return Codes 


typedef struct { 
char major_rc[2]; 
char minor_rc[2]; 
} _Maj_Min_rc_T; 


The following macros are defined in recio.h: 


_FILENAME_MAX 
Expands to an integral constant expression that is the size of a character 
array large enough to hold the longest file name. This is the same as the 
stream I/O macro. 
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_ROPEN_MAX 


Expands to an integral constant expression that is the maximum number of 
files that can be opened simultaneously. 


The following null field macros are defined in recio.h: 


Element 
Description 


_CLEAR_NULL_MAP(file, type) 
Clears the null output field map that indicates that there are no null fields 


in the record to be written to file. type is a typedef that corresponds to the 
null field map for the current record format. 


_CLEAR_UPDATE_NULL_MAP(file, type) 
Clears the null input field map that indicates that no null fields are in the 
record to be written to file. type is a typedef that corresponds to the null 
field map for the current record format. 


_QRY_NULL_MAPé(file, type) 
Returns the number of fields that are null in the previously read record. 


type is a typedef that corresponds to the null field map for the current 
record format. 


_CLEAR_NULL_KEY_MAP(file, type) 
Clears the null key field map so that it indicates no null key fields in the 
record to be written to file. type is a typedef that corresponds to the null 
key field map for the current record format. 


SET_NULL_MAP_FIELD(file, type, field) 
Sets the specified field in the output null field map so that field is 
considered NULL when the record is written to file. 


_SET_UPDATE_NULL_MAP_FIELD(file, type, field) 
Sets the specified field in the input null field map so that field is 
considered null when the record is written to file. type is a typedef that 
corresponds to the null key field map for the record format. 


QRY_NULL_MAP _FIELD(file, type, field) 
Returns 1 if the specified field in the null input field map indicates that the 
field is to be considered null in the previously read record. If field is not 
null, it returns zero. type is a typedef that corresponds to the NULL key 
field map for the current record format. 


SET_NULL_KEY_MAP_FIELD(file, type, field) 
Sets the specified field map that indicates that the field will be considered 
null when the record is read from file. type is a typedef that corresponds to 
the null key field map for the current record format. 


QRY_NULL_KEY_MAP(file, type) 
Returns the number of fields that are null in the key of the previously read 


record. type is a typedef that corresponds to the null field map for the 
current record format. 


QORY_NULL_KEY_MAP_ FIELD (file, type, field) 
Returns 1 if the specified field in the null key field map indicates that field 
is to be considered null in the previously read record. If field is not null, it 


returns zero. type is a typedef that corresponds to the null key field map 
for the current record format. 
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<regex.h> 


The <regex.h> include file defines the following regular expression functions: 


regcomp () regerror() regexec() regfree() 


The <regex.h> include file also declares the regmatch_t type, the regex_t type, which 
is capable of storing a compiled regular expression, and the following macros: 


Values of the cflags parameter of the regcomp () function: 


REG_BASIC 
REG_EXTENDED 
REG_ICASE 
REG_NEWLINE 
REG_NOSUB 


Values of the eflags parameter of the regexec() function: 


REG_NOTBOL 
REG_NOTEOL 


Values of the errcode parameter of the regerror() function: 


REG_NOMATCH 
REG_BADPAT 
REG_ECOLLATE 
REG_ECTYPE 
REG_EESCAPE 
REG_ESUBREG 
REG_EBRACK 
REG_EPAREN 
REG_EBRACE 
REG_BADBR 
REG_ERANGE 
REG_ESPACE 
REG_BADRPT 
REG_ECHAR 
REG_EBOL 
REG_EEOL 
REG_ECOMP 
REG_EEXEC 
REG_LAST 


These declarations and definitions are accessible only when 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) is specified on the 
compilation command. 


<setjmp.h> 


The <setjmp.h> include file declares the ket imp ()I macro and Long imal function. It 
also defines a buffer type, jmp_buf, that the setjmp() macro and longjmp function 
use to save and restore the program state. 
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<signal.h> 


The <signal.h> include file defines the values for signals and declares the 
and fraise()| functions. 


The <signal.h> include file also defines the following macros: 


SIGABRT SIG_ERR SIGILL SIGOTHER SIGUSRI 
SIGALL SIGFPE SIGINT SIGSEGV SIGUSR2 
SIG_DFL SIG_IGN SIGIO SIGTERM 


<signal.h> also declares the function GetExcData, an iSeries extension to the C 
standard library. 


<stdarg.h> 
The <stdarg.h> include file defines macros that_allow_you_access to arguments in 
functions with variable-length argument lists: Carey = | and lva_ 
The <stdarg.h> include file also defines the type va_list. 

<stddef.h> 


The <stddef.h> include file declares the commonly used pointers, variables, and 
types as listed below: 
ptrdiff_t 

typedef for the type of the difference of two pointers 


size_t typedef for the type of the value that is returned by sizeof 


wehar_t 
typedef for a wide character constant. 


The <stddef.h> include file also defines the macros NULL and offsetof. NULL is a 
pointer that is guaranteed not to point to a data object. The offsetof macro 
expands to the number of bytes between a structure member and the start of the 
structure. The of fsetof macro has the form: 


offsetof(structure_type, member) 


The <stddef.h> include file also declares the extern variable EXCP_MSGID, an 
iSeries extension to C. 
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<stdio.h> 


The <stdio.h> include file defines constants, macros, and types, and declares 
stream input and output functions. The stream I/O functions are: 


clearerr fputs getchar scant wprintf * 
fclose fputwc? gets setbuf wscanf + 
feof fputws? getwc t setvbuf 
ferror fread getwchar ! snprintf 
fflush freopen perror sprintf 
fgetc fscanf printf sscanf 
fgetpos fseek putc tmpfile 
fgets fsetpos putchar tmpnam 
fgetwe * ftell puts ungetc 
fgetws } fwide ! putwc + ungetwc ? 
fileno” fwprintf ? putwchar ? vfprintf 
fopen fwrite remove vfwprintf ? 
fprintf fwscanf ? rename vprintf 
fputc getc rewind vsnprintf 
_fputchar vsprintf 
vwprintf ? 
Note: 


' These functions are available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are 
specified on the compilation command. 


? These functions are available when SYSIFCOPT(*IFSIO)is specified on 
the compilation command. 


The <stdio.h> include file also defines the macros that are listed below. You can 
use these constants in your programs, but you should not alter their values. 


BUFSIZ Specifies the buffer size that the setbuf library function will use when you 
are allocating buffers for stream I/O. This value establishes the size of 
system-allocated buffers and is used with setbuf. 


EOF The value that is returned by an I/O function when the end of the file (or 
in some cases, an error) is found. 


FOPEN_MAX 
The number of files that can be opened simultaneously. 


FILENAME MAX 
The longest file name that is supported. If there is no reasonable limit, 
FILENAME_MAX will be the recommended size. 


L_tmpnam 
The size of the longest temporary name that can be generated by the 
tmpnam function. 


TMP_MAX 
The minimum number of unique file names that can be generated by the 
tmpnam function. 


NULL A pointer guaranteed not to point to a data object. 
The FILE structure type is defined in <stdio.h>. Stream I/O functions use a 


pointer to the FILE type to get access to a given stream. The system uses the 
information in the FILE structure to maintain the stream. 
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When integrated file system is enabled with a compilation parameter 
SYSIFCOPT(*IFSIO), ifs.h is included into <stdio.h>. 


The C standard streams stdin, stdout, and stderr are also defined in <stdio.h>. 


The macros SEEK_CUR, SEEK_END, and SEEK_SET expand to integral constant 
expressions and can be used as the third argument to fseek(). 


The macros _IOFBF, IOLBF, and _IONBF expand to integral constant expressions 
with distinct values suitable for use as the third argument to the setvbuf function. 


The type fpos_t is defined in <stdio.h> for use with fgetpos() and fsetpos(). 


See for more information on NULL. 


<stdlib.h> 


The <stdlib.h> include file declares the following functions: 


bhard] haid 

bh hidid aaa 

btexitl band 

btorl fhe keallad 

btoil fnstawes) Erand 

btoll fnbt-awcl Etrtod 
hutenv 


Note: ' These functions are applicable to C++ only. 


The <stdlib.h> include file also contains definitions for the following macros: 
NULL The NULL pointer value. 


EXIT_SUCCESS 
Expands to 0; used by the atexit function. 


EXIT_FAILURE 
Expands to 8; used by the atexit function. 


RAND_MAX 
Expands to an integer that represents the largest number that the rand 
function can return. 


MB_CUR_MAX 
Expands to an integral expression to represent the maximum number of 
bytes in a multibyte character for the current locale. 


For more information on NULL and the types size_t and wchar_t, see 
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<string.h> 


The <string.h> include file declares the string manipulation functions: 


Note: ' These functions are applicable to C++ only. 


The <string.h> include file also defines the macro NULL, and the type size_t. 


For more information on NULL and the type size_t, see /<stddef h>” on page 14 


| <strings.h> 


| Contains the functions strcasecmp and strncasecmp 


<time.h> 


The <time.h> include file declares the time and date functions: 


bsctimd ktimel pmtimeymtime d [Localtime d tind 
Elocl Wi fttimd (trftind 


The <time.h> include file also provides: 


* A structure tm a contains the components of a calendar time. See ’gmtime(] 
for a list of the tm structure members. 


* A macro CLOCKS_PER_ SEC eae to the number per second of the value that is 
returned by the ‘clock function. 


* Types clock_t, time_t, and size t. 
* The NULL pointer value. 


For more information on NULL and the type size_t, see 
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<wchar.h> 


The <wchar.h> header file contains declarations and definitions that are related to 
the manipulation of wide character strings. Any functions which deal with files are 
accessible if SYSIFCOPT(*IFSIO) is specified. 


Vsworin wesrtombs* 
nee eran 


fgetwc? intf? wet 
fgetws? oe fmemcmpl 
fputwc* mbsrtowcs? wcsicmp* lymemcpyl 
fputws* putwc* wcesnicmp* wosto hymemmoval 
fwide? putwohar’ wescoll? 
fwprint f? westol1+ weswidth? 
fwscanf? swscanf? westoul]* meee 
getwc* ungetwc* 
getwchar® vfwprintf? 

wscanf@ 

wprintf? 
Note: 


' These functions are available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


? These functions are available only when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) are specified on the compilation command. 


<westr.h> 
The<westr.h> include file declares the multibyte functions: 
licscatl lucsncad bcswed 
eS tas 
bicscmal 
<wcestr.h> also defines the types size_t, NULL, and wchar_t. 
For more information on NULL and the types size_t and wchar_t, see 
<wctype.h> 
The <wctype.h> header file contains declarations and definitions for wide character 
classification. These declarations and definitions are accessible only when 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) is specified on the 
compilation command. 
<xxcvt.h> 


The <xxcvt.h> include file contains the declarations that are used by the QXXDTOP, 
QXXDTOZ, QXXITOP, QXXITOZ, QXXPTOI, QXXPTOD, QXXZTOD, and QXXZTOI conversion 
functions. 
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<xxdtaa.h> 


The <xxdtaa.h> include file contains the declarations for the data area interface 
functions QXXCHGDA, QXXRTVDA, and the type _DTAA_NAME_T. 


The definition of DTAA NAME T is: 


typedef struct _DTAA_NAME_T { 
char dtaa_name[10]; 
char dtaa_lib[10]; 
}_DTAA_NAME_T; 


<xxenv.h> 


The <xxenv.h> include file contains the declarations for the QPXXCALL and QPXXDLTE 
EPM environment handling program. ILE procedures cannot be called from this 
interface. 


The definition of _ENVPGM_T is: 


typedef struct _ENVPGM T { 
char pgmname[10]; 
char pgmlib[10]; 

} _ENVPGM_T; 


<xxfdbk.h> 


The <xxfdbk.h> include file contains the declarations that are used by the OS/400 


The following is an example of a type that is defined in the <xxfdbk.h> include 
file: 
typedef Packed struct _XXIOFB_T { 


short file_dep_fb_offset; 
int write_count; 
int read_count; 
int write_read_count; 
int other_io_count; 
char reservedl; 
char cur_operation; 
char rec_format[10]; 
char dev_class[2]; 
char dev_name[10] ; 
int last_io_rec_len; 
char reserved2[80] ; 
short num_recs_retrieved; 
short last_io_rec_len2; 
char reserved3[2]; 
int cur_blk_count; 
char reserved4[8] ; 

} _XXIOFB_T; 


For further information on the open feedback areas, see the File Managemen] topic 
in the Information Center. 


Machine Interface (Ml) Include Files 


See the ILE C/C++ for AS/400 MI Library Reference for a description of the MI 
header files. 
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Chapter 2. Library Functions 


This chapter describes the standard C library functions and the ILE C extensions to 
the library functions, except for the ILE C MI functions. See the ILE C/C++ for 
AS/400 MI Library Reference for more information about the MI functions. 


Each library function that is listed in this section contains: 

* A format description that shows the include file that declares the function. 
* The data type that is returned by the function. 

* The required data types of the arguments to the function. 


This example shows the format of the 1og() function: 


#include <math.h> 
double log(double x); 


The example shows that: 

* you must include the file math.h in the program. 

* the log() function returns type double. 

* the log() function requires an argument x of type double. 


Examples throughout the section illustrate the use of library functions and are not 
necessarily complete. 


This chapter lists the library functions in alphabetic order. If you are unsure of the 
function you want to use, see the summary of the library functions in 


The C Library 


This chapter summarizes the available C library functions and their location in this 
book. It also briefly describes what the function does. Each library function is 
listed according to the type of function it performs. 


Error Handling 


Function Header File Page Description 

assert () assert.h hal Prints diagnostic messages. 

atexit() stdlib.h hal Registers a function to be 
executed at program end. 

clearerr() stdio.h ka] Resets error indicators. 

feof () stdio.h 9) Tests end-of-file indicator 
for stream input. 

ferror() stdio.h 9] Tests the error indicator for 
a specified stream. 

perror() stdio.h fog Prints an error message to 
stderr. 
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Function 


Header File 


Description 


_GetExcData() 


signal.h 


Retrieves information about 
an exception from within a 
C signal handler. This 
function is not defined 
when 
SYSIFCOPT(*SYNCSIGNAL) 
is specified on the 
compilation command. 


raise() 


signal.h 


Initiates a signal. 


signal () 


signal.h 


E] 8] 


Allows handling of an 
interrupt signal from the 
operating system. 


strerror() 


string.h 


Retrieves pointer to system 
error message. 


Searching and Sorting 


Function Header File Page Description 

bsearch() stdlib.h ie Performs a binary search of a sorted 
array. 

qsort() stdlib.h bid Performs a quick sort on an array 
of elements. 

Mathematical 

Function Header File Page Description 

abs() stdlib.h B8 Calculates the absolute value of an 
integer. 

ceil () math.h kal Calculates the double value 
representing the smallest integer 
that is greater than or equal to a 
number. 

div() stdlib.h Calculates the quotient and 
remainder of an integer. 

erf() math.h 0] Calculates the error function. 

erfc() math.h 2] Calculates the error function for 
large numbers. 

exp () math.h 3] Calculates an exponential function. 

fabs() math.h Za Calculates the absolute value of a 
floating-point number. 

floor() math.h bil Calculates the double value 
representing the largest integer that 
is less than or equal to a number. 

fmod() math.h bil Calculates the floating point 
remainder of one argument 
divided by another. 

frexp() math.h fu) Separates a floating-point number 
into its mantissa and exponent. 

gamma () math.h ie Calculates the gamma function. 
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Function Header File Page Description 

hypot () math.h had Calculates the hypotenuse. 

labs() stdlib.h 154 Calculates the absolute value of a 
long integer. 

llabs() stdlib.h fs Calculates the absolute value of a 
long long integer. 

ldexp() math.h 5d Multiplies a floating-point number 
by an integral power of 2. 

ldiv() stdlib.h 5d Calculates the quotient and 
remainder of a long integer. 

lidiv() stdlib.h 5d Calculates the quotient and 
remainder of a long long integer. 

log() math.h hed Calculates natural logarithm. 

1og10() math.h fled Calculates base 10 logarithm. 

modf () math.h hod Calculates the signed fractional 
portion of the argument. 

pow() math.h Lod Calculates the value of an 
argument raised to a power. 

sqrt () math.h Bid Calculates the square root of a 
number. 


Trigonometric Functions 


Function Header File Page Description 

acos() math.h Bg] Calculates the arc cosine. 

asin() math.h 3] Calculates the arc sine. 

atan() math.h Bl Calculates the arc tangent. 
atan2() math.h | Calculates the arc tangent. 

cos() math.h kal Calculates the cosine. 

cosh() math.h kl Calculates the hyperbolic cosine. 
sin() math.h Bid Calculates the sine. 

sinh() math.h Bid Calculates the hyperbolic sine. 
tan() math.h bz Calculates the tangent. 

tanh() math.h bz Calculates the hyperbolic tangent. 


Bessel Functions 


Function Header File Page Description 

j0() math.h El 0 order differential equation of the 
first kind. 

jlQ math.h ail 1st order differential equation of 
the first kind. 

jn() math.h ail nth order differential equation of 
the first kind. 

y0() math.h ail 0 order differential equation of the 
second kind. 
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Function Header File Page Description 

yl() math.h Ei] 1st order differential equation of 
the second kind. 

yn() math.h al nth order differential equation of 


the second kind. 


Time Manipulation 


Function Header File | Page Description 
asctime() time.h lad Converts time stored as a structure 
to a character string in storage. 
asctime_r() time.h 4d Converts time stored as a structure 
to a character string in storage. 
(Restartable version of asctime()) 
clock() time.h | Determines processor time. 
ctime() time.h 64 Converts time stored as a long 
value to a character string. 
ctime_r() time.h Converts time stored as a long 
value to a character string. 
(Restartable version of ctime()) 
difftime() time.h 6d Calculates the difference between 
two times. 
gmt ime () time.h (41) Converts time to Coordinated 
Universal Time structure. 
gmtime_r() time.h Converts time to Coordinated 
Universal Time structure. 
(Restartable version of gmt ime()) 
localtime() time.h faa) Converts time to local time. 
localtime_r() time.h heal Converts time to local time. 
(Restartable version of localtime()) 
mktime() time.h boa Converts local time into calendar 
time. 
time() time.h bz Returns the time in seconds. 


Type Conversion 


Function Header File | Page Description 

atof() stdlib.h ad Converts a character string to a 
floating-point value. 

atoi() stdlib.h | Converts a character string to an 
integer. 

atol() stdlib.h 5d Converts a character string to a 
long integer. 

strtod() stdlib.h B57 Converts a character string to a 
double value. 

strtol () stdlib.h Bed) Converts a character string to a 


long integer. 
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Function Header File _| Page Description 

strtoll1() stdlib.h Bad) Converts a character string to a 
long long integer. 

strtoul () stdlib.h Bed Converts a string to an unsigned 
long integer. 

strtoull() stdlib.h Beal Converts a string to an unsigned 
long long integer. 

toascii() ctype.h Bzd Converts a character to the 
corresponding ASCII value. 

westod() wchar.h 422) Converts a wide-character string to 
a double floating point. 

westol () wchar.h 424] Converts a wide-character string to 
a long integer. 

westol] wchar.h 42a] Converts a wide-character string to 
a long long integer. 

westoul () wchar.h 43d) Converts a wide-character string to 
an unsigned long integer. 

westuol] wchar.h 430 Converts a wide-character string to 
an unsigned long long integer. 

Conversion 

Function Header File Page Description 

QXXDTOP () xxevt.h Converts a floating-point value to a 
packed decimal value. 

QXXDTOZ() xxevt.h b2d Converts a floating-point value to a 
zoned decimal value. 

QXXITOP() xxevt.h b21] Converts an integer value to a 
packed decimal value. 

QXXITOZ() xxevt.h boil Converts an integer value to a 
zoned decimal value. 

QXXPTOD () xxevt.h bod Converts a packed decimal value 
to a floating-point value. 

QXXPTOI () xxevt.h bod Converts a packed decimal value 
to an integer value. 

QXXZTOD() xxevt.h bol Converts a zoned decimal value to 
a floating-point value. 

QXXZTOI () xxevt.h bod Converts a zoned decimal value to 
an integer value. 


Record Input/Output 


Function Header File _| Page Description 

_Racquire() recio.h baal Prepares a device for record I/O 
operations. 

_Rclose() recio.h 229 Closes a file that is opened for 


record I/O operations. 
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Function Header File Page Description 

_Rcommit () recio.h bad Completes the current transaction, 
and establishes a new commitment 
boundary. 

_Rdelete() recio.h b3a| Deletes the currently locked record. 

_Rdevatr() recio.h baa Returns a pointer to a copy of the 

xxfdbk.h device attributes feedback area for 
the file reference by fp and the 
device pgmdev. 

_Rfeod() recio.h Forces an end-of-file condition for 
the file referenced by fp. 

_Rfeov() recio.h bad Forces an end-of-volume condition 
for tapes. 

_Rformat () recio.h 49 Sets the record format to fmt for the 
file referenced by fp. 

_Rindara() recio.h sil Sets up the separate indicator area 
to be used for subsequent record 
I/O operations. 

_Riofbk() recio.h B52] Returns a pointer to a copy of the 

xxfdbk.h I/O feedback area for the file 
referenced by fp. 

_Rlocate() recio.h B54) Positions to the record in the files 
associated with fp and specified by 
the key, klen_rrn and opt 
parameters. 

_Ropen() recio.h B57 Opens a file for record I/O 
operations. 

_Ropnfbk() recio.h Rel Returns a pointer to a copy of the 

xxfdbk.h open feedback area for the file 
referenced by fp. 

_Rpgmdev () recio.h bed] Sets the default program device. 

_Rreadd() recio.h baal Reads a record by relative record 
number. 

_Rreadf() recio.h bas Reads the first record. 

_Rreadindv() recio.h bed Reads data from an invited device. 

_Rreadk() recio.h bz Reads a record by key. 

_Rread] () recio.h bzal Reads the last record. 

_Rreadn() recio.h bz Reads the next record. 

_Rreadnc() recio.h bzal Reads the next changed record in 
the subfile. 

_Rreadp() recio.h Reads the previous record. 

_Rreads() recio.h bsal Reads the same record. 

_Rrelease() recio.h bs3l Makes the specified device 
ineligible for record I/O operations. 

_Rrisick() recio.h bed Releases the currently locked 
record. 

_Rrollbck() recio.h bsd Reestablishes the last commitment 
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boundary as the current 
commitment boundary. 


Function Header File 


Page 


Description 


_Rupdate() recio.h Writes to the record that is 
currently locked for update. 

_Rupfb() recio.h baal Updates the feedback structure with 
information about the last record 
I/O operation. 

_Rwrite() recio.h boil Writes a record to the end of the 
file. 

_Rwrited() recio.h baal Writes a record by relative record 
number. It will only write over 
deleted records. 

_Rwriterd() recio.h bod Writes and reads a record. 

_Rwrread() recio.h bod Functions as _Rwriterd(), except 


separate buffers may be specified 
for input and output data. 


Stream Input/Output 


Formatted Input/Output 


Function Header File 


Description 


fprintf() stdio.h 


Formats and prints 
characters to the 
output stream. 


fscanf() stdio.h 


Reads data from a 
stream into 
locations given by 
arguments. 


fwprintf() stdio.h 


fwscanf() stdio.h 


Format data as a 
wide character and 
write it to a 
stream. 


Read data from 
stream using 
wide-character 
string. 


printf () stdio.h 


SS 
i> 
=) 


Formats and prints 
characters to 
stdout. 


scanf () stdio.h 


Reads data from 
stdin into 
locations given by 
arguments. 


snprintf() stdio.h 


Same as sprintf, 
except that the 
snprintf() 
function will stop 
after n characters 
have been written 
to outbuf. 


sprintf () stdio.h 


Formats and 
writes characters 
to a buffer. 
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Function 


Header File 


Page 


Description 


sscanf () 


stdio.h 


Reads data from a 
buffer into 
locations given by 
arguments. 


swprintf() 


wchar.h 


Format and write 
wide characters to 
buffer. 


swscanf () 


wchar.h 


Reads wide data 
from a buffer into 
locations given by 
arguments. 


vfprintf () 


stdio.h 
stdarg.h 


oe 
0 
on 


Formats and prints 
characters to the 
output stream 
using a variable 
number of 
arguments. 


vfwprintf () 


stdio.h 
stdarg.h 


Format argument 
data as wide 
characters and 
write to a stream. 


vprintf() 


stdarg.h 
stdio.h 


Formats and 
writes characters 
to stdout using a 
variable number of 
arguments. 


vsnprintf () 


stdio.h 
stdarg.h 


Same as vsprintf, 
except that the 
vsnprintf function 
will stop after n 
characters have 
been written to 
outbuf. 


vsprintf () 


stdarg.h 
stdio.h 


Formats and 
writes characters 
to a buffer using a 
variable number of 
arguments. 


vswprintf () 


stdio.h 
stdarg.h 


Format and write 
wide characters to 
buffer using a 
variable number of 
arguments. 


vwprintf () 


stdio.h 
stdarg.h 


Format argument 
data as wide 
characters and 
print using a 
variable number of 
arguments. 


wprintf () 


wchar.h 


Format data as 
wide characters 
and print. 
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Function Header File Page Description 


wscanf () wchar.h had Read data using 
wide-character 
format string. 


Character and String Input/Output 


Function Header File _| Page Description 

fgetc() stdio.h gd Reads a character from a specified 
input stream. 

fgets () stdio.h 4 Reads a string from a specified 
input stream. 

fgetwc() stdio.h 84 Reads wide character from stream. 

fgetws() stdio.h 89 Reads wide-character string from 
stream. 

fputc() stdio.h foil Prints a character to a specified 
output stream. 

fputs() stdio.h fos) Prints a string to a specified output 
stream. 

fputwc() stdio.h fL04) Writes wide character. 

fputws () stdio.h [Lod Writes wide-character string. 

getc() stdio.h Reads a character from a specified 
input stream. 

getchar() stdio.h Reads a character from stdin. 

gets () stdio.h ey Reads a line from stdin. 

getwc() stdio.h [33] Reads wide character from stream. 

getwchar() stdio.h fi40) Gets wide character from stdin. 

putc() stdio.h bid Prints a character to a specified 
output stream. 

putchar() stdio.h bid Prints a character to stdout. 

puts () stdio.h bi Prints a string to stdout. 

putwc() stdio.h bid Writes wide character. 

putwchar() stdio.h bial Writes wide character to stdout. 

ungetc() stdio.h Bail Pushes a character back onto a 
specified input stream. 

ungetwc() stdio.h Bsa] Pushes wide character onto input 
stream. 

Direct Input/Output 

Function Header File Page Description 

fread() stdio.h 108 Reads items from a specified input 
stream. 

fwrite() stdio.h fod Writes items to a specified output 
stream. 


Chapter 2. Library Functions 29 


File Positioning 


Function Header File Page Description 


fgetpos() stdio.h kal Gets the current 
position of the 
file pointer. 


fseek() stdio.h hid Moves the file 
pointer to a new 
location. 


fseeko() stdio.h Same as 
fseek(). 
fsetpos() stdio.h Moves the file 
pointer to a new 
location. 
ftell() stdio.h Gets the current 
position of the 
file pointer. 
ftello() stdio.h Same as 
ftell(). 
rewind() stdio.h Repositions the 


file pointer to 
the beginning of 


the file. 

File Access 

Function Header File Page Description 

fclose() stdio.h Bl Closes a specified stream. 

fdopen() stdio.h Za Associates an input or output 
stream with a file. 

fflush() stdio.h Causes the system to write the 
contents of a buffer to a file. 

fopen() stdio.h bo] Opens a specified stream. 

freopen() stdio.h hol Closes a file and reassigns a 
stream. 

fwide() stdio.h fod Determines stream orientation. 

setbuf () stdio.h Bod Allows control of buffering. 

setvbuf () stdio.h Bul Controls buffering and buffer size 
for a specified stream. 

wfopen() stdio.h had Opens a specified stream, accepting 
file name and mode as wide 
characters. 

File Operations 

Function Header File Page Description 

fileno() stdio.h 90 Determines the file handle. 

remove () stdio.h 43 Deletes a specified file. 

rename () stdio.h bad Renames a specified file. 
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Handling Argument Lists 


Function Header File Page Description 

tmpfile() stdio.h Bzd Creates a temporary file and 
returns a pointer to that file. 

tmpnam() stdio.h Bz Produces a temporary file name. 


Function Header File Page Description 

va_arg() stdarg.h bad Allows access to variable number of 
function arguments. 

va_end() stdarg.h Bs] Allows access to variable number of 
function arguments. 

va_start() stdarg.h bad Allows access to variable number of 
function arguments. 


Pseudorandom Numbers 


Function Header File Page Description 

rand(), rand_r() stdlib.h 22d Returns a pseudorandom integer. 
(rand_r() is the restartable version 
of rand().) 

srand() stdlib.h B19 Sets the starting point for 


pseudorandom numbers. 


Dynamic Memory Management 


Function 


Header File 


Page 


Description 


_C_TS_malloc_info 


mallocinfo.h 


hd 


Returns the current memory 
usage information. 


_C_TS_malloc_debug 


mallocinfo.h 


iz 


Returns the same information as 
_C_TS_malloc_info, plus produces 
a spool file of detailed 
information about the memory 
structure used by malloc 
functions when compiled with 
teraspace. 


calloc() stdlib.h 5d Reserves storage space for an 
array and initializes the values of 
all elements to 0. 

free() stdlib.h ita) Frees storage blocks. 

malloc() stdlib.h Liza) Reserves storage blocks. 

realloc() stdlib.h b34] Changes storage size allocated for 


an object. 
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Memory Objects 


Function Header File _| Page Description 

memchr () string.h isd Searches a buffer for the first 
occurrence of a given character. 

memecmp () string.h baal Compares two buffers. 

memcpy () string.h Copies a buffer. 

memmove () string.h foil Moves a buffer. 

memset () string.h 9a) Sets a buffer to a given value. 

wmemchr () wchar.h ad) Locates a wide character in a 
wide-character buffer. 

wmemcmp () wchar.h 43] Compares two wide-character 
buffers. 

wmemcpy () wchar.h 44] Copies a wide-character buffer. 

wmemmove () wchar.h 45] Moves a wide-character buffer. 

wmemset () wchar.h ad Sets a wide-character buffer to a 
given value. 


Environment Interaction 


Function 


Header File 


Page 


Description 


abort () 


stdlib.h 


Ends a program 
abnormally. 


exit () 


stdlib.h 


Ends the program 
normally if called in the 
initial thread. 


getenv() 


stdlib.h 


Searches environment 
variables for a specified 
variable. 


_C_Get_Ssn_Handle() 


stdio.h 


Returns a handle to the 
C session for use with 
DSM APIs. 


localeconv() 


long jmp () 


locale.h 


setjmp.h 


El 


Formats numeric 
quantities in struct lconv 
according to the current 
locale. 


Restores a stack 
environment. 


nl_langinfo() 


langinfo.h 


E] 


Retrieves information 
from the current locale. 


putenv() 


stdlib.h 


El 


Sets the value of an 
environment variable by 
altering an existing 
variable or creating a 
new one. 


set jmp () 


setjmp.h 


El 


Saves a stack 
environment. 


setlocale() 


locale.h 


El 


Changes or queries 
locale. 
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Function 


Header File 


Page 


Description 


system() 


stdlib.h 


bzd 


Passes a string to the 
operating system’s 
command interpreter. 


String Operations 


Function Header File Page Description 
strcasecmp strings.h Compares strings without case 
Snel sensitivity. 
pen On 
strncasecmp strings.h Compares strings without case 
Snel sensitivity. 
pen On 
strcat() string.h B24 Concatenates two strings. 
strchr() string.h B24 Locates the first occurrence of a 
specified character in a string. 
strcmp () string.h B2d Compares the value of two strings. 
strcoll() string.h B29 Compares the locale-defined value 
of two strings. 
strcpy() string.h B3d Copies one string into another. 
strcspn() string.h B31 Finds the length of the first 
substring in a string of characters 
not in a second string. 
strfmon() string.h bad Converts monetary value to string. 
strftime() time.h 3d Converts date and time to a 
formatted string. 
strlen() string.h ball Calculates the length of a string. 
strncat() string.h bad Adds a specified length of one 
string to another string. 
strncmp() string.h bad Compares two strings up to a 
specified length. 
strncpy() string.h bad Copies a specified length of one 
string into another. 
strpbrk() string.h bad Locates specified characters in a 
string. 
strptime() time.h sd Converts string to formatted time. 
strrchr() string.h B54 Locates the last occurrence of a 
character within a string. 
strspn() string.h Bsa Locates the first character in a 
string that is not part of specified 
set of characters. 
strstr() string.h b5d Locates the first occurrence of a 


string in another string. 
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Function Header File Page Description 

strtok() string.h sd Locates a specified token in a 
string. 

strtok_r() string.h Ball Locates a specified token in a 
string. (Restartable version of 
strtok()). 

strxfrm() string.h Bed Transforms strings according to 
locale. 

wesftime() wchar.h hod Converts to formatted date and 
time. 

wesstr() wehar.h hol Locates a wide-character substring. 

westok() wchar.h hod Tokenizes a wide-character string. 


Character Testing 


Function Header File Page Description 

isalnum() ctype.h 47 Tests for alphanumeric characters. 

isalpha() ctype.h Tests for alphabetic characters. 

isascii() ctype.h 144 Tests for ASCII values. 

iscntr1() ctype.h 47 Tests for control characters. 

isdigit() ctype.h 4d Tests for decimal digits. 

isgraph() ctype.h Tests for printable characters 
excluding the space. 

islower() ctype.h Tests for lowercase letters. 

isprint() ctype.h Tests for printable characters 
including the space. 

ispunct() ctype.h had Tests for printable characters 
excluding the space. 

isspace() ctype.h had Tests for white-space characters. 

isupper() ctype.h had Tests for uppercase letters. 

isxdigit() ctype.h Tests for wide hexadecimal digits 0 
through 9, a through f, or A 
through F. 


Multibyte Character Testing 


Function Header File Page Description 

iswalnum() wctype.h fd Tests for wide alphanumeric 
characters. 

iswalpha() wctype.h hsd Tests for wide alphabetic 
characters. 

iswentr1() wctype.h fsd Tests for wide control characters. 

iswctype() wctype.h 5d Tests for character property. 

iswdigit() wctype.h fd Tests for wide decimal digits. 

iswgraph() wctype.h isd Tests for wide printing characters 


excluding the space. 
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Function Header File Page Description 

iswlower() wctype.h isd Tests for wide lowercase letters. 

iswprint() wctype.h isd Tests for wide printing characters. 

iswpunct() wctype.h fd Tests for wide non-alphanumeric, 
non-space characters. 

iswspace() wctype.h isd Tests for wide whitespace 
characters. 

jswupper() wctype.h isd Tests for wide uppercase letters. 

iswxdigit() wctype.h f5d Tests for wide hexadecimal digits 0 


through 9, a through f, or A 
through F. 


Character Case Mapping 


Function Header File Page Description 

tolower() ctype.h Bzd Converts a character to lowercase. 

toupper() ctype.h Bzd Converts a character to uppercase. 

towlower() ctype.h Converts a wide character to 
lowercase. 

towupper() ctype.h Bzd Converts a wide character to 


uppercase. 


Multibyte Character Manipulation 


Function Header File Page Description 
btowc() stdio.h 54] Converts a single byte to a wide 
wcehar.h character. 

mblen() stdlib.h bz Determines length of string of 
multibyte character. 

mbrlen() stdlib.h hz Determines the length of a 
multibyte character. (Restartable 
version of mblen()) 

mbrtowc() stdlib.h zd Converts a multibyte character to a 
wide character. (Restartable version 
of mbtowc()) 

mbsinit() stdlib.h iz Tests state object for initial state. 

mbsrtowcs() stdlib.h isd Converts a multibyte string to a 
wide character string. (Restartable 
version of mbstowcs()) 

mbstowcs () stdlib.h isd Converts a multibyte string to a 
wide <wchart.h>string. 

mbtowc () stdlib.h lsd Converts multibyte characters to a 
wide <wchart.h>character. 

towctrans () wctype.h Bz Translates wide character. 

wcrtomb () stdlib.h Bod Converts a wide character to a 


multibyte character. (Restartable 
version of wctomb()). 
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Function Header File Page Description 

wesrtombs () stdlib.h hid Converts a wide character string to 
a multibyte character string. 
(Restartable version of wcstombs()). 

wcstombs () stdlib.h hod Converts a wide character string to 
a multibyte character string. 

wescat() westr.h Concatenates wide character 
strings. 

weschr() westr.h hod Searches a wide character string for 
a wide character. 

wescmp () westr.h hod Compares two wide character 
strings. 

wcscoll() westr.h hod Compares the locale-defined value 
of two wide-character strings. 

wescpy () westr.h hod Copies a wide character string. 

wescspn() westr.h Searches a wide character string for 
characters. 

weslen() westr.h 409 Finds length of a wide character 
string. 

wesncat() westr.h hid Concatenates a wide character 
string segment. 

wesncmp () westr.h kul Compares wide character string 
segments. 

wesncpy() westr.h TT Copies wide character string 
segments. 

wcspbrk() westr.h id Locates wide characters in string. 

wesspn() westr.h Finds number of wide characters. 

wesrchr() westr.h bid Locates wide character in string. 

wcswcs () westr.h hd Locates a wide character string in 
another wide character string. 

wceswidth() wchar.h had Determines the display width of a 
wide character string. 

wesxfrm() westr.h h3) Transforms wide-character strings 
according to locale. 

wcetob() stdlib.h hag Converts a wide character to a 
single byte. 

wctomb () stdlib.h had Converts wide characters to 
multibyte characters. 

wctrans () wetype.h bad Gets a handle for character 
mapping. 

wctype() wchar.h had Obtains a handle for character 
property classification. 

wewidth() wchar.h had Determines the display width of a 
wide character. 
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Data Areas 


Function Header File Page Description 

QXXCHGDA() xxdtaa.h big Changes the data area. 

QXXRTVDA() xxdtaa.h ee Retrieves a copy of the data area 
specified by dtname. 


Message Catalogs 


Function Header File Page Description 

catclose() nl_types.h Ed Closes a message catalog. 

catgets() nl_types.h Esl Reads a message from an opened 
message catalog. 

catopen() nl_types.h 5) Opens a message catalog. 

Regular Expression 

Function Header File Page Description 

regcomp () regex.h b3d Compiles regular expression. 

regexec() regex.h bad Executes compiled regular 
expression. 

regerror() regex.h b3d Returns error message for regular 
expression. 

regfree() regex.h baJ Frees memory for regular 
expression. 


abort() — Stop a Program 


Format 


#include <stdlib.h> 
void abort(void); 


Language Level: ANSI 


Thread Safe: YES. 


Description 


The abort() function causes an abnormal end of the program and returns control 
to the host environment. Like the exit() function, the abort() function deletes 
buffers and closes open files before ending the program. 


Calls to the abort() function raise the SIGABRT signal. The abort() function will 
not result in the ending of the program if SIGABRT is caught by a signal handler, 
and the signal handler does not return. 


Note: When compiled with SYSIFCOPT(*ASYNCSIGNAL), the abort() function 


cannot be called in a signal handler. 


Return Value 
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There is no return value. 
Example that uses abort () 


This example tests for successful opening of the file myfile. If an error occurs, an 
error message is printed, and the program ends with a call to the abort() function. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 
FILE «stream; 


if ((stream = fopen("mylib/myfile", "r")) == NULL) 
{ 
perror("Could not open data file"); 
abort(); 
} 
} 


Related Information 


¢ See the signal() API in the Eystem API Referencd 


abs() — Calculate Integer Absolute Value 


Format 
#include <stdlib.h> 


int abs(int n); 

Language Level: ANSI 

Thread Safe: NO. 

Description 

The abs() function returns the absolute value of an integer argument n. 
Return Value 

There is no error return value. The result is undefined when the absolute value of 
the argument cannot be represented as an integer. The value of the minimum 
allowable integer is defined by INT_MIN in the <limits.h> include file. 
Example that uses abs () 

This example calculates the absolute value of an integer x and assigns it to y. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 
int x = -4, y; 


y = abs(x); 
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printf("The absolute value of x is %d.\n", y); 


[RRRRRERERERARRERERERE QUEPUL FER RRR EAA RRA AA REAR RR ERE RE 


The absolute value of x is 4. 
KR KIRA KKK AK KKK KKK KKK IK KKK KKK KKK KA KKK KK EAA ERK KER | 


} 


Related Information 


acos() — Calculate Arccosine 


Format 


#include <math.h> 
double acos(double x); 


Language Level: ANSI 
Thread Safe: NO. 
Description 


The acos() function calculates the arccosine of x, expressed in radians, in the range 
0 toll. 


Return Value 


The acos() function returns the arccosine of x. The value of x must be between -1 
and 1 inclusive. If x is less than -1 or greater than 1, acos() sets errno to EDOM 
and returns 0. 


Example that uses acos() 


This example prompts for a value for x. It prints an error message if x is greater 
than 1 or less than -1; otherwise, it assigns the arccosine of x to y. 
#include <stdio.h> 


#include <stdlib.h> 
#include <math.h> 


#define MAX 1.0 
#define MIN -1.0 


int main(void) 
{ 
double x, y; 


printf( "Enter x\n" ); 
scanf( "%1f", &x ); 


/* Output error if not in range */ 
if (x > MAX ) 

printf( "Error: %1f too large for acos\n", x ); 
else if ( x < MIN ) 

printf( "Error: %1f too small for acos\n", x ); 
else { 
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y = acos( x ); 
printf( "acos( %1f ) = %1f\n", x, y ); 
} 
} 


/xxxxxx* Expected output if 0.4 is entered: ******««« 
Enter x 

acos( 0.400000 ) = 1.159279 

*/ 


Related Information 


asctime() — Convert Time to Character String 


40 


Format 


#include <time.h> 
char *asctime(const struct tm *time); 


Language Level: ANSI 
Thread Safe: NO. Use asctime_r() instead. 
Description 


The asctime() function converts time, stored as a structure pointed to by time, to a 
character string. You can obtain the time value from a call to the gmtime() function 
or the localtime() function; either returns a pointer to a tm structure defined in 
<time.h>. 


The string result that asctime() produces contains exactly 26 characters and has 
the format: 


"5.35 %.38%3d %.2d:%.2d:%.2d %d\n" 


The following are examples of the string returned: 


Sat Jul 16 02:03:55 1994\n\0 
or 
Sat Jul 16 2:03:55 1994\n\0 


The asctime() function uses a 24-hour-clock format. The days are abbreviated to: 
Sun, Mon, Tue, Wed, Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, 
Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. All fields have constant 
width. Dates with only one digit are preceded either with a zero or a blank space. 
The new-line character (\n) and the null character (\0) occupy the last two 
positions of the string. 
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The time and date functions begin at 00:00:00 Universal Time, January 1, 1970. 
Return Value 


The asctime() function returns a pointer to the resulting character string. If the 
function is unsuccessful, it returns NULL. 


Note: The asctime(), ctime() functions, and other time functions may use a 
common, statically allocated buffer to hold the return string. Each call to one 
of these functions may destroy the result of the previous call. The 
asctime_r(), ctime_r(), gmtime_r(), and localtime_r()functions do not use 
a common, statically-allocated buffer to hold the return string. These 
functions can be used in the place of the asctime(), ctime(), gmtime(), and 
localtime() functions if reentrancy is desired. 


Example that uses asctime() 


This example polls the system clock and prints a message that gives the current 
time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 
struct tm *newtime; 
time_t ltime; 


/* Get the time in seconds */ 
time(&ltime) ; 

/* Convert it to the structure tm */ 
newtime = localtime(&ltime) ; 


/* Print the local time as a string */ 
printf("The current date and time are %s", 
asctime(newtime) ) ; 


} 


[EKRKEKEKERERKR Output should be similar tO: ***kXKKKKKKEKKKKEEK 
The current date and time are Fri Sep 16 13:29:51 1994 
*/ 


Related Information 
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asctime_r() — Convert Time to Character String (Restartable) 
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Format 


#include <time.h> 
char *asctime_r(const struct tm *tm, char *buf); 


Thread Safe: NO. 
Description 
This function is the restartable version of the asctime() function. 


The asctime_r() function converts time, stored as a structure pointed to by tm, to 
a character string. You can obtain the tm value from a call to gmtime_r() or 
localtime_r(); either returns a pointer to a tm structure defined in <time.h>. 


The string result that asctime_r() produces contains exactly 26 characters and has 
the format: 


"5.35 %.38%3d %.2d:%.2d:%.2d %d\n" 


The following are examples of the string returned: 


Sat Jul 16 02:03:55 1994\n\0 
or 
Sat Jul 16 2:03:55 1994\n\0 


The asctime_r() function uses a 24-hour-clock format. The days are abbreviated to: 
Sun, Mon, Tue, Wed, Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, 
Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. All fields have constant 
width. Dates with only one digit are preceded either with a zero or a blank space. 
The new-line character (\n) and the null character (\0) occupy the last two 
positions of the string. 


The time and date functions begin at 00:00:00 Universal Time, January 1, 1970. 
Return Value 


The asctime_r() function returns a pointer to the resulting character string. If the 
function is unsuccessful, it returns NULL. 


Example that uses asctime_r() 


This example polls the system clock and prints a message giving the current time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 


struct tm *newtime; 
time_t ltime; 
char mybuf[50]; 


/* Get the time in seconds */ 
time(&ltime) ; 
/* Convert it to the structure tm */ 
newtime = localtime_r(&ltime()); 
/* Print the local time as a string */ 
printf("The current date and time are %s", 
asctime_r(newtime, mybuf)); 
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} 


[KEKRKEKEKEREKRKR Output should be similar tO ***k*kKKKKKKKKKKKK 
The current date and time are Fri Sep 16 132951 1994 
*/ 


Related Information 


asin() — Calculate Arcsine 


Format 


#include <math.h> 
double asin(double x); 


Language Level: ANSI 

Thread Safe: NO. 

Description 

The asin() function calculates the arcsine of x, in the range -1/2 to m/2 radians. 
Return Value 


The asin() function returns the arcsine of x. The value of x must be between -1 
and 1. If x is less than -1 or greater than 1, the asin() function sets errno to 
EDOM, and returns a value of 0. 


Example that uses asin() 


This example prompts for a value for x. It prints an error message if x is greater 
than 1 or less than -1; otherwise, it assigns the arcsine of x to y. 
#include <stdio.h> 


#include <stdlib.h> 
#include <math.h> 


#define MAX 


1.0 
#define MIN -1.0 


int main(void) 
{ 
double x, y; 
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printf( "Enter x\n" ); 
scanf( "%1f", &x )3 


/* Output error if not in range */ 
if (x > MAX ) 
printf( "Error: %1f too large for asin\n", x ); 
else if ( x < MIN ) 
printf( "Error: %1f too small for asin\n", x ); 
else 
{ 
y = asin( x ); 
printf( "asin( %1f ) = %1f\n", x, y )3 
} 
} 


[KRKRKEKRKEREKKE Output should be similar tO ****XXKKKKKKKKKKKE 
Enter x 

asin( 0.200000 ) = 0.201358 

x/ 


Related Information 


assert() — Verify Condition 


Format 


#include <assert.h> 
void assert(int expression); 


Language Level: ANSI 
Thread Safe: NO. 
Description 


The assert() function prints a diagnostic message to stderr and aborts the 
program if expression is false (zero). The diagnostic message has the format: 


Assertion failed: expression, file filename, line line-number. 
The assert() function takes no action if the expression is true (nonzero). 


Use the assert() function to identify program logic errors. Choose an expression 
that holds true only if the program is operating as you intend. After you have 
debugged the program, you can use the special no-debug identifier NDEBUG to 
remove the assert() calls from the program. If you define NDEBUG to any value 
with a #define directive, the C preprocessor expands all assert calls to void 
expressions. If you use NDEBUG, you must define it before you include 

in the program. 
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Return Value 
There is no return value. 


Note: The assert() function is defined as a macro. Do not use the #undef 
directive with assert(). 


Example that uses assert () 


In this example, the assert() function tests string for a null string and an empty 
string, and verifies that length is positive before processing these arguments. 


#include <stdio.h> 
#include <assert.h> 


void analyze (char *, int); 


int main(void) 
{ 
char *string 
int length = 


= "ABC's 
3; 
analyze(string, length); 


printf("The string %s is not null or empty, " 
"and has length %d \n", string, length); 
} 


void analyze(char *string, int length) 


{ 


assert(string != NULL); /* cannot be NULL «/ 
assert(*string != '\0'); /* cannot be empty */ 
assert(length > 0); /* must be positive */ 


} 


[KEKRKRKKEKKREKKR Output should be similar tO *xkkXxKKKKKKEKKKKK 
The string ABC is not null or empty, and has length 3 


Related Information 


Reference . 


atan() — atan2() — Calculate Arctangent 


Format 


#include <math.h> 
double atan(double x); 
double atan2(double y, double x); 


Language Level: ANSI 
Description 


The atan() and atan2() functions calculate the arctangent of x and y/x, 
respectively. 


Return Value 
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The atan() function returns a value in the range -7/2 to m/2 radians. The atan2() 
function returns a value in the range -7 to 7 radians. If both arguments of the 
atan2() function are zero, the function sets errno to EDOM, and returns a value of 
0. 


Example that uses atan() 


This example calculates arctangents using the atan() and atan2() functions. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 


double a,b,c,d; 


c = 0.45; 

d = 0.23; 

a = atan(c); 

b = atan2(c,d); 


printf("atan( %1f ) = %1 
printf("atan2( %1f, %1f 


(ns C.8)'s 
= %1f/n", c, d, b); 


as 


} 


[KEKRKKKRKKERKKE Output Should be similar tO *x***KXKKKKKKKKKKKK 
atan( 0.450000 ) = 0.422854 
atan2( 0.450000, 0.230000 ) = 1.098299 


KKK KKK KKK KKK AK KKK KKK KK KKK KKK AK KAKI KKK AK KIRK KKK KKK AKER AKER KK | 


Related Information 


atexit() — Record Program Ending Function 
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Format 


#include <stdlib.h> 
int atexit(void (*func) (void)); 


Language Level: ANSI 

Description 

The atexit() function records the function, pointed to by func, that the system 
calls at normal program end. For portability, you should use the atexit() function 


to register a maximum of 32 functions. The functions are processed in a last-in, 
first-out order. The atexit() function cannot be called from the OPM default 
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activation group. Most functions can be used with the atexit function; however, if 
the exit function is used the atexit function will fail. 


Return Value 
The atexit() function returns 0 if it is successful, and nonzero if it fails. 
Example that uses atexit() 


This example uses the atexit() function to call goodbye() at program end. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 
void goodbye(void); 
int rc; 


rc = atexit(goodbye) ; 


if (rc != 0) 
perror("Error in atexit"); 
exit(0); 


} 


void goodbye(void) 
/* This function is called at normal program end */ 
{ 
printf("The function goodbye was called at program end\n"); 


} 


[KEKRKEKEKEREKER Output should be similar tO: ***kXKKKKKKEKKKKEK 


The function goodbye was called at program end 
x/ 


Related Information 


atof() — Convert Character String to Float 


Format 
#include <stdlib.h> 


double atof(const char *string); 
Language Level: ANSI 


Description 


The atof() function converts a character string to a double-precision floating-point 
value. 


The input string is a sequence of characters that can be interpreted as a numeric 
value of the specified return type. The function stops reading the input string at 
the first character that it cannot recognize as part of a number. This character can 
be the null character that ends the string. 
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The atof() function expects a string in the following form: 


>> digits > 
whitespace | + | | Luigits— | 
- .—digits 
Yeevaccroscsmee 0 a9 
e digits 
eI Ls 


The white space consists of the same characters for which the isspace() function is 
true, such as spaces and tabs. The atof() function ignores leading white-space 
characters. 


For the atof() function, digits is one or more decimal digits; if no digits appear 
before the decimal point, at least one digit must appear after the decimal point. 
The decimal digits can precede an exponent, introduced by the letter e or E. The 
exponent is a decimal integer, which may be signed. 


The atof() function will not fail if a character other than a digit follows an E or if 
e is read in as an exponent. For example, 100elf will be converted to the 
floating-point value 100.0. The accuracy is up to 17 significant character digits. 


Return Value 


The atof() function returns a double value that is produced by interpreting the 
input characters as a number. The return value is 0 if the function cannot convert 
the input to a value of that type. The return value is undefined in case of overflow. 


Example that uses atof () 


This example shows how to convert numbers that are stored as strings to numeric 
values. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 


double x; 
char *s; 
s = " -2309.12E-15"; 

atof(s); /* xX = -2309.12E-15 */ 


printf("x = %.4e\n",x); 


} 


[KEKRKKERKKERKEKERERE Output should be similar to: **x*#kx*kkKKKKEKKK 


x = -2.309le-12 
x/ 


Related Information 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


atoi() — Convert Character String to Integer 


Format 


#include <stdlib.h> 
int atoi(const char *string); 


Language Level: ANSI 
Description 


The atoi() function converts a character string to an integer value. The input 
string is a sequence of characters that can be interpreted as a numeric value of the 
specified return type. The function stops reading the input string at the first 
character that it cannot recognize as part of a number. This character can be the 
null character that ends the string. 


The atoi() function does not recognize decimal points nor exponents. The string 
argument for this function has the form: 


>>. 


digits >< 


whitespace | + 


where whitespace consists of the same characters for which the isspace() function 
is true, such as spaces and tabs. The atoi () function ignores leading white-space 
characters. The value digits represents one or more decimal digits. 


Return Value 


The atoi() function returns an int value that is produced by interpreting the input 
characters as a number. The return value is 0 if the function cannot convert the 
input to a value of that type. The return value is undefined in the case of an 
overflow. 


Example that uses atoi () 


This example shows how to convert numbers that are stored as strings to numeric 
values. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 
int i; 
char *S; 


S 
i 


" 9885"; 
atoi(s); /* i = -9885 */ 


printf("i = %d\n",i); 
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[KEKRKKERKEKERKKERERE Output should be similar to: ***#kx*kkkKKKEKKKK 


atol() — atoll() — Convert Character String to Long or Long Long 


Integer 


Format (atol ()) 


#include <stdlib.h> 
long int atol(const char *string); 


Format (atol1()) 


#include <stdlib.h> 
long long int atoll(const char *string); 


Language Level: ANSI 
Description 


The atol() function converts a character string to a long value. The atol1 () 
function converts a character string to a long long value. 


The input string is a sequence of characters that can be interpreted as a numeric 
value of the specified return type. The function stops reading the input string at 
the first character that it cannot recognize as part of a number. This character can 
be the null character that ends the string. 


The atol() and atol1() functions do not recognize decimal points nor exponents. 
The string argument for this function has the form: 


digits 
Lag teesnace-! KH 


>>. >< 


where whitespace consists of the same characters for which the isspace() function 
is true, such as spaces and tabs. The atol() and atol1() functions ignore leading 
white-space characters. The value digits represents one or more decimal digits. 


Return Value 


The atol() and atol1() functions return a long or a long long value that is 
produced by interpreting the input characters as a number. The return value is OL 
if the function cannot convert the input to a value of that type. The return value is 
undefined in case of overflow. 
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Example that uses atol () 


This example shows how to convert numbers that are stored as strings to numeric 
values. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 
long 13 
char *S; 


s 
] 


"98854 dollars"; 
atol(s); /* 1 = 98854 «/ 


printf("1 = %.1d\n",1); 
} 


[KEKRKKKKKKERKEREREKE Output should be similar tO: **x**xkkKKKKKKKK 


1 = 98854 
*/ 


Related Information 


Bessel Functions 


Format 


#include <math.h> 

double jQ(double x); 

double jl(double x); 

double jn(int n, double x); 
double yQ(double x); 

double yl(double x); 

double yn(int n, double x); 


Language Level: ILE C Extension 

Description 

Bessel functions solve certain types of differential equations. The j0(), j1(), and 
jn() functions are Bessel functions of the first kind for orders 0, 1, and n, 
respectively. The y0(), y1(), and yn() functions are Bessel functions of the second 


kind for orders 0, 1, and n, respectively. 


The argument x must be positive. The argument n should be greater than or equal 
to zero. If n is less than zero, it will be a negative exponent. 


Return Value 


For j0(), j1(), y0(), or y1(), if the absolute value of x is too large, the function 
sets errno to ERANGE, and returns 0. For y0(), y1(), or yn(), if x is negative, the 
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function sets errno to EDOM and returns the value -HUGE_VAL. For y0, y1(), or 
yn(), if x causes overflow, the function sets errno to ERANGE and returns the 
value -HUGE_VAL. 


Example that uses Bessel Functions 


This example computes y to be the order 0 Bessel function of the first kind for x. It 
also computes z to be the order 3 Bessel function of the second kind for x. 


#include <math.h> 
#include <stdio.h> 


int main(void) 

{ 
double x, y, Z3 
x = 4.27; 


jO(x); /* y = -0.3660 is the order 0 bessel */ 
/* function of the first kind for x */ 
yn(3,x)3 /* z = -0.0875 is the order 3 bessel */ 
/* function of the second kind for x */ 


y 


Z 


printf("y = %1f\n", y)s 
printf("z = %1f\n", 2); 


} 


[KEKRKKEREREREKER Output should be Similar tOr *X**XKKKKKKKKKKKKKKEKKK 
y = -0.366022 
z = -0.087482 


KKK KKK KKK KEKE AK KEK KKK KKK KKK IKEA KK EAR EAR A KKK EKA A KER AK KERKE | 


Related Information 


bsearch() — Search Arrays 


Format 


#include <stdlib.h> 
void *bsearch(const void «key, const void «base, 
size_t num, size_t size, 
int (*compare) (const void «key, const void *element)); 


Language Level: ANSI 
Description 


The bsearch() function performs a binary search of an array of num elements, each 
of size bytes. The array must be sorted in ascending order by the function pointed 
to by compare. The base is a pointer to the base of the array to search, and key is the 
value being sought. 


The compare argument is a pointer to a function you must supply that compares 
two items and returns a value specifying their relationship. The first item in the 
argument list of the compare() function is the pointer to the value of the item that 
is being searched for. The second item in the argument list of the compare() 
function is a pointer to the array element being compared with the key. The 
compare() function must compare the key value with the array element and then 
return one of the following values: 
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Value Meaning 

Less than 0 key less than element 

0 key identical to element 
Greater than 0 key greater than element 


Return Value 


The bsearch() function returns a pointer to key in the array to which base points. If 
two keys are equal, the element that key will point to is unspecified. If the 
bsearch() function cannot find the key, it returns NULL. 


Example that uses bsearch() 


This example performs a binary search on the argv array of pointers to the 
program parameters and finds the position of the argument PATH. It first removes 
the program name from argv, and then sorts the array alphabetically before calling 
bsearch(). The comparel() and compare2() functions compare the values pointed 
to by arg1 and arg2 and return the result to the bsearch() function. 

#include <stdlib.h> 


#include <stdio.h> 
#include <string.h> 


int comparel(const void *, const void *); 
int compare2(const void *, const void *); 


main(int argc, char *argv[]) 


{ /* This program performs a binary */ 
char **result; /* search on the argv array of pointers */ 
char *key = "PATH"; /* to the program parameters. It first */ 
int i; /* removes the program name from argv */ 

/* then sorts the array alphabetically */ 
argvt+; /* before calling bsearch. */ 
argc--; 


qsort((char *)argv, argc, sizeof(char *), comparel); 
result = (char**)bsearch(&key, (char *)argv, argc, sizeof(char *), compare2); 
if (result != NULL) { 
printf("result =<%s>\n",*result) ; 
else printf("result is null\n"); 
/*This function compares the values pointed to by argl */ 
/*and arg2 and returns the result to qsort. argl and */ 


/*arg2 are both pointers to elements of the argv array. */ 


int comparel(const void *argl, const void *arg2) 


{ 
} 


return (strcemp(*(char **)argl, *(char **)arg2)); 


/*This function compares the values pointed to by argl */ 
/*and arg2 and returns the result to bsearch x/ 
/*argl is a pointer to the key value, arg2 points to */ 
/*the element of argv that is being compared to the key */ 
/*value. */ 


int compare2(const void *argl, const void *arg2) 
{ 


return (strcemp(*(char **)argl, *(char **)arg2)); 
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} 


[eek Output should be similar to: ******eeKEEX 
result = <PATH> 

KkRKKKKKKKKKKRKEEK When the input on the iSeries command line is *******x 
CALL BSEARCH PARM(WHERE IS PATH IN THIS PHRASE'?') 

*/ 


Related Information 


btowc() — Convert Single Byte to Wide Character 


Format 


#include <stdio.h> 
#include <wchar.h> 
wint_t btowc(int c); 


Language Level: ANSI 
Description 


The btowc() function converts the single byte value c to the wide-character 
representation of c. If c does not constitute a valid (one-byte) multibyte character in 
the initial shift state, the btowc() function returns WEOF. 


The behavior of the btowc() function is affected by the LC_CTYPE category of the 
current locale. This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Note: If a program is compiled with LOCALETYPE(*LOCALEUCS2), the btowc () 
function will behave as if the program was compiled with 
LOCALETYPE(*LOCALE), because the btowc() function does not support 
UNICODE. 


Return Value 


The btowc() function returns WEOF if c has the value EOF, or if (unsigned char) c 
does not constitute a valid (one-byte) multibyte character in the initial shift state. 
Otherwise, it returns the wide-character representation of that character. 


Example that uses btowc() 


This example scans various types of data. 
#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <local .h> 


#define UPPER_LIMIT OxFF 
int main(void) 
{ 

int we; 

int ch; 
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if (NULL == setlocale(LC_ALL, "")) { 
printf("Locale could not be loaded\n"); 
exit(1); 


} 
for (ch = 0; ch <= UPPER_LIMIT; ++ch) { 
we = btowc(ch); 
if (wc==WEOF) { 
printf ("%#04x is not a one-byte multibyte character\n", ch); 
} else { 
printf ("%#04x has wide character representation: %#06x\n", ch, wc); 


} 


we = btowc(EOF); 
if (wc==WEOF) { 
printf("The character is EOF.\n", ch); 
} else { 
printf("EOF has wide character representation: %#06x\n", wc); 
} 


return 0; 


} 


[RR KKK KKK KEK AKER KER AK KEIR EAR K KEK AKAIKE IKEA IKEA KKK AKER AKER 
If the locale is bound to SBCS, the output should be similar to: 
0000 has wide character representation: 000000 
0x01 has wide character representation: 0x0001 


Oxfe has wide character representation: Ox00fe 
Oxff has wide character representation: Ox00ff 
The character is EOF. 


If the locale is bound to DBCS, the output should be similar to: 
0000 has wide character representation: 000000 
0x01 has wide character representation: 0x0001 


0x80 has wide character representation: 0x80 
0x83 is not a one-byte multibyte character 


Oxa2 has wide character representation: 0xa2 


Oxff has wide character representation: Ox00ff 
The character is EOF. 
KKK AK KKK KK EAR KER KKK AK KEK KKK KKK KKK AKER I KK AKK EA AKER AKER AKER KEKE | 


Related Information 


_C_Get_Ssn_Handle() — Handle to C Session 


Format 
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#include <stdio.h> 


_SSN_HANDLE_T _C_Get_Ssn_Handle (void) 
Language Level: ILE C Extension 
Description 


Returns a handle to the C session for use with Dynamic Screen Manager (DSM) 
APIs. 


Return Value 
The C Get Ssn_Handle() function returns a handle to the C session. If an error 


occurs, SSN HANDLE T is set to zero. See the topic for more information 
about using the _C_Get_Ssn_Handle() function with DSM APIs. 


calloc() — Reserve and Initialize Storage 
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Format 


#include <stdlib.h> 
void *calloc(size_t num, size_t size); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The calloc() function reserves storage space for an array of num elements, each of 
length size bytes. The calloc() function then gives all the bits of each element an 
initial value of 0. 


Return Value 


The calloc() function returns a pointer to the reserved space. The storage space to 
which the return value points is suitably aligned for storage of any type of object. 
To get a pointer to a type, use a type cast on the return value. The return value is 
NULL if there is not enough storage, or if num or size is 0. 


Note: To use Teraspace storage instead of heap storage without changing the C 
source code, specify the TERASPACE(*YES *TSIFC) parameter on the 
compiler command. This maps the calloc() library function to 
_C_TS_calloc(), its Teraspace storage counterpart. The maximum amount of 
Teraspace storage that can be allocated by each call to _C_TS_calloc() is 
2GB - 224, or 2147483424 bytes. 


For more information about Teraspace, see the ILE Concepts manual. 
Example that uses calloc() 
This example prompts for the number of array entries required, and then reserves 


enough space in storage for the entries. If calloc() is successful, the example 
prints out each entry; otherwise, it prints out an error. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 


long * array; /* start of the array 

x/ 

long * index; /* index variable 

x/ 

int is /* index variable 

x/ 

int num; /* number of entries of the array 
x/ 


printf( "Enter the size of the array\n" ); 
scanf( "%i", &num); 


/* allocate num entries */ 
if ( (index = array = (long *) calloc( num, sizeof( long ))) != NULL ) 
{ 


for (i = 0; i < num; ++i ) /* put values in arr */ 
*indext+ = i; /* using pointer no */ 

for ( i = 0; i < num; ++i 
printf( "array[%i ] 

} 


else 
{ /* out of storage */ 
perror( "Out of storage" ); 
abort(); 
} 
} 


[KEK RKERKEKKERKEREKE Output Should be similar tO: **XkKKKKKKKKKKKKKKKKKK 


) /* print the array out */ 
i\n", i, array[i] ); 


iT} 
owe 4 


Enter the size of the array 


array[ 0 ] = 0 
array[ 1] = 1 
array[ 2] = 2 
x/ 


Related Information 


catclose() — Close Message Catalog 


Format 

#include <nl_types.h> 

int catclose (nl_catd catd); 
Language Level: XPG4 
Thread Safe: YES. 


Description 


The catclose() function closes the previously opened message catalog that is 
identified by catd. 
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Note: This function is only accessible when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) and SYSIFCOPT(*IFSIO) are specified on the 
compilation command. 


Return Value 


If the close is performed successfully, 0 is returned. Otherwise, -1 is returned 
indicating failure, which may happen if catd is not a valid message catalog 
descriptor. 


The value of errno may be set to: 


EBADF 
The catalog descriptor is not valid. 


EINTR 
The function was interrupted by a signal. 


Example that uses catclose() 


#include <stdio.h> 
#include <nl_types.h> 
#include <locale.h> 
/* Name of the message catalog is "/qsys.lib/mylib.lib/msgs.usrspc" */ 
int main(void) { 
nl_catd msg file; 
char * my_msg; 
char * my_locale; 


setlocale(LC_ALL, NULL); 
msg _file = catopen("/qsys.lib/mylib.lib/msgs.usrspc", 0); 


if (msg file != CATD_ERR) { 
my_msg = catgets(msg file, 1, 2, "“oops"); 
printf("%s\n", my_msg); 
catclose(msg_file); 


} 
} 


Related Information 


catgets() — Retrieve a Message from a Message Catalog 
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Format 

#include <nl_types.h> 

char *catgets(nl_catd catd, int set_id, int msg_id, char *s); 
Language Level: XPG4 

Thread Safe: YES. 


Description 
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The catgets() function retrieves message imsg_id, in set set_id from the message 
catalog that is identified by catd. catd is a message catalog descriptor that is 
returned by a previous call to catopen(). The s argument points to a default 
message which will be returned by catgets() if the identified message cannot be 
retrieved. 


Note: This function is only accessible when LOCALETYPE(*LOCALE) or 
LOCALETYPE(#*LOCALEUCS2) and SYSIFCOPT(*IFSIO) are specified on the 
compilation command. 


Return Value 


If the message is retrieved successfully, then catgets() returns a pointer to the 
message string that is contained in the message catalog. If the message is retrieved 
unsuccessfully, then a pointer to the default string s is returned. 


The value of errno may be set to the following: 


EBADF 
The catalog descriptor is not valid. 


EINTR 
The function was interrupted by a signal. 


Example that uses catgets() 


#include <stdio.h> 
#include <nl_types.h> 
#include <locale.h> 
/* Name of the message catalog is "/qsys.lib/mylib.1lib/msgs.usrspc" */ 
int main(void) { 
nl_catd msg _ file; 
char * my_msg; 


char * my_locale; 


setlocale(LC_ALL, NULL); 
msg_file = catopen("/qsys.lib/mylib.lib/msgs.usrspc", 0); 


if (msg_file != CATD_ERR) { 
my_msg = catgets(msg file, 1, 2, "“oops"); 
printf("%s\n", my_msg); 
catclose(msg file); 


} 
} 


Related Information 


catopen() — Open Message Catalog 


Format 
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#include <nl_types.h> 
nl_catd catopen(const char *name, int oflag); 


Language Level: XPG4 
Thread Safe: YES. 
Description 


The catopen() function opens a message catalog, which must be done before a 
message can be retrieved. The NLSPATH environment variable and the 
LC_MESSAGES category are used to find the specified message catalog if no slash 
(/) characters are found in the name. If the name contains one or more slash (/) 
characters, then the name is interpreted as a path name of the catalog to open. 


If there is no NLSPATH environment variable, or if a message catalog cannot be 
found in the path specified by NLSPATH, then a default path will be used. The 
default path may be affected by the setting of the LC_MESSAGES locale category if 
the value of oflag is NL_CAT_LOCALE, or by the LANG environment variable if 
the value of oflag is zero. 


The message catalog descriptor will remain valid until it is closed by a call to 
catclose(). If the LC_MESSAGES locale category is changed, it may invalidate 
existing open message catalogs. 


Note: This function is only accessible when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) and SYSIFCOPT(*IFSIO) are specified on the 
compilation command. The name of the message catalog must be a valid 
Integrated File System file name. 


The catopen() function might fail under the following conditions, and the value of 
errno may be set to: 


EMFILE 
NL_MAXOPEN message catalogs are currently open. 


EACCES 
Insufficient authority to read the message catalog specified, or to search the 
component of the path prefix of the message catalog specified. 


ENAMETOOLONG 
The length of the path name of the message catalog exceeds PATH_MAX, 
or a path name component is longer than NAME_MAX. 


ENFILE 
Too many files are currently open in the system. 


ENOENT 
The message catalog does not exist, or the name argument points to an 
empty string. 


Return Value 


If the message catalog is opened successfully, then a valid catalog descriptor is 
returned. If catopen() is unsuccessful, then it returns CATD_ERR ((nl_catd)-1). 


Example that uses catopen() 
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#include <stdio.h> 
#include <nl_types.h> 
#include <locale.h> 
/* Name of the message catalog is "/qsys.lib/mylib.1lib/msgs.usrspc" */ 
int main(void) { 
nl_catd msg_file; 
char * my_msg; 


char * my_locale; 


setlocale(LC_ALL, NULL); 
msg_file = catopen("/qsys.lib/mylib.lib/msgs.usrspc", 0); 


if (msg file != CATD_ERR) { 
my_msg = catgets(msg file, 1, 2, "oops"); 
printf("%s\n", my_msg); 
catclose(msg file); 


} 
} 


Related Information 


ceil() — Find Integer >=Argument 
Format 
#include <math.h> 
double ceil(double x); 
Language Level: ANSI 


Description 


The ceil() function computes the smallest integer that is greater than or equal to 
at: 


Return Value 
The ceil() function returns the integer as a double value. 
Example that uses ceil () 


This example sets y to the smallest integer greater than 1.05, and then to the 
smallest integer greater than -1.05. The results are 2.0 and -1.0, respectively. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 
double y, Z; 


ceil(1.05); /* y 
ceil(-1.05); /* Zz 


2.0 */ 
-1.0 */ 


y 
z 


printf("y = %.2f ; z = %.2f\n", y, Z)s 
} 


[KEKRKKEREKEREKER Output Should be Similar tO: *X*KKXKKKKKKEKKKKKKEKEK 


y = 2.00 ; z = -1.00 
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Related Information 


clearerr() — Reset Error Indicators 


Format 


#include <stdio.h> 
void clearerr (FILE *stream) ; 


Language Level: ANSI 
Description 


The clearerr() function resets the error indicator and end-of-file indicator for the 
specified stream. Once set, the indicators for a specified stream remain set until 
your program calls the clearerr() function or the rewind() function. The fseek() 
function also clears the end-of-file indicator. The ILE C/C++ run-time environment 
does not automatically clear error or end of file indicators. 


Return Value 
There is no return value. 


The value of errno may be set to: 
Value Meaning 


EBADF 
The file pointer or descriptor is not valid. 


ENOTOPEN 
The file is not open. 


ESTDIN 
stdin cannot be opened. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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Example that uses clearerr() 


This example reads a data stream, and then checks that a read error has not 
occurred. 


#include <stdio.h> 
#include <stdlib.h> 


FILE «stream; 
int c; 


int main(void) 
{ 
if ((stream = fopen("mylib/myfile", "r")) != NULL) 


if ((c=getc(stream)) == EOF) 


if (ferror(stream) ) 
{ 
perror("Read error"); 
clearerr(stream) ; 
} 
} 
} 
else 
exit(0); 
} 


Related Information 


clock() — Determine Processor Time 


Format 

#include <time.h> 

clock_t clock(void); 

Language Level: ANSI 

Description 

The clock() function returns an approximation of the processor time used by the 
program since the beginning of an implementation-defined time-period that is 
related to the process invocation. To obtain the time in seconds, divide the value 
that is returned by clock() by the value of the macro CLOCKS_PER_SEC. 


Return Value 


If the value of the processor time is not available or cannot be represented, the 
clock() function returns the value (clock_t)-1. 
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To measure the time spent in a program, call clock() at the start of the program, 
and subtract its return value from the value returned by subsequent calls to 
clock(). On other platforms, you can not always rely on the clock() function 
because calls to the system() function may reset the clock. 


Example that uses clock() 
This example prints the time that has elapsed since the program was called. 


#include <time.h> 
#include <stdio.h> 


double timel, timedif; /* use doubles to show small values */ 


int main(void) 


{ 


int i; 
timel = (double) clock(); /* get initial time */ 
timel = timel / CLOCKS PER SEC; /* in seconds x/ 


/* running the FOR loop 10000 times */ 
for (i=0; i<10000; i++); 


/* call clock a second time */ 
timedif = ( ((double) clock()) / CLOCKS PER SEC) - timel; 
printf("The elapsed time is %1lf seconds\n", timedif); 


} 


Related Information 


cos() — Calculate Cosine 


Format 

#include <math.h> 
double cos(double x); 
Language Level: ANSI 


Description 


The cos() function calculates the cosine of x. The value x is expressed in radians. If 
x is too large, a partial loss of significance in the result may occur. 


Return Value 


The cos() function returns the cosine of x. The value of errno may be set to either 
EDOM or ERANGE. 


Example that uses cos () 


This example calculates y to be the cosine of x. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double x, y3; 


Xx 
y 


Tes 
cos(x); 


printf("cos( %1f ) = %1f\n", x, y); 


[KEKRKEKRKRKKERKERERKERERK Output Should be similar tO:  **XXKKKKKKKKKKKKKKK 


cos( 7.200000 ) = 0.608351 
*/ 


Related Information 


cosh() — Calculate Hyperbolic Cosine 


Format 

#include <math.h> 
double cosh(double x); 
Language Level: ANSI 


Description 


The cosh() function calculates the hyperbolic cosine of x. The value x is expressed 
in radians. 


Return Value 


The cosh() function returns the hyperbolic cosine of x. If the result is too large, 
cosh() returns the value HUGE_VAL and sets errno to ERANGE. 


Example that uses cosh() 


This example calculates y to be the hyperbolic cosine of x. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 
double x,y; 


7.2 


xX 3 
cosh(x); 


¥ 


printf("cosh( %1f ) = %1f\n", x, y)s 
} 


[KEK KKKERKEKERKEKERERE RK Output should be similar tO: ****KKKKKKKKKKKKKEK 


cosh( 7.200000 ) = 669.715755 
*/ 


Related Information 


ctime() — Convert Time to Character String 
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Format 


#include <time.h> 
char *ctime(const time_t *time); 


Language Level: ANSI 
Thread Safe: NO. Use ctime_r() instead. 
Description 


The ctime() function converts the time value pointed to by time to local time in 
the form of a character string. A time value is usually obtained by a call to the 
time() function. 


The string result that is produced by ctime() contains exactly 26 characters and 
has the format: 


"5.35 %.38%3d %.2d:%.2d:%.2d %d\n" 


For example: 
Mon Jul 16 02:03:55 1987\n\0 


The ctime() function uses a 24-hour clock format. The days are abbreviated to: 
Sun, Mon, Tue, Wed, Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, 
Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. All fields have a constant 
width. Dates with only one digit are preceded with a zero. The new-line character 
(\n) and the null character (\0) occupy the last two positions of the string. 


Return Value 
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The ctime() function returns a pointer to the character string result. If the function 
is unsuccessful, it returns NULL. A call to the ctime() function is equivalent to: 


asctime(localtime(&anytime) ) 


Note: The asctime() and ctime() functions, and other time functions may use a 
common, statically allocated buffer to hold the return string. Each call to one 
of these functions may destroy the result of the previous call. The 
asctime_r(), ctime_r(), gmtime_r(), and localtime_r() functions do not 
use a common, statically-allocated buffer to hold the return string. These 
functions can be used in the place of asctime(), ctime(), gmtime(), and 
localtime() if reentrancy is desired. 


Example that uses ctime() 


This example polls the system clock using time(). It then prints a message giving 
the current date and time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 
{ 


time_t ltime; 
time(localtime()); 


printf("the time is %s", ctime(localtime())); 


} 


Related Information 


ctime_r() — Convert Time to Character String (Restartable) 


Format 
#include <time.h> 
char *ctime_r(const time_t *time, char *buf); 


Description 


This function is the restartable version of the ctime() function. 
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The ctime_r() function converts the time value pointed to by time to local time in 
the form of a character string. A time value is usually obtained by a call to the 
time() function. 


The string result that is produced by the ctime_r() function contains exactly 26 
characters and has the format: 


"5.35 %.38%3d %.2d:%.2d:%.2d %d\n" 


For example: 
Mon Jul 16 02:03:55 1987\n\0 


The ctime_r() function uses a 24-hour clock format. The days are abbreviated to: 
Sun, Mon, Tue, Wed, Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, 
Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. All fields have a constant 
width. Dates with only one digit are preceded with a zero. The new-line character 
(\n) and the null character (\0) occupy the last two positions of the string. 


Return Value 


The ctime_r() function returns a pointer to the character string result. If the 
function is unsuccessful, it returns NULL. A call to ctime_r() is equivalent to: 


asctime_r(localtime_r(&anytime, buf), buf) 
where buf is a pointer to char. 
Example that uses ctime_r() 


This example polls the system clock using ctime_r(). It then prints a message 
giving the current date and time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 


time_t ltime; 
char buf[50]; 


time(localtime()); 


printf("the time is %s", ctime_r(localtime(), buf)); 


} 


Related Information 
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difftime() — Compute Time Difference 
Format 
#include <time.h> 
double difftime(time_t time2, time_t timel); 
Language Level: ANSI 


Description 


The difftime() function computes the difference in seconds between time2 and 
time. 


Return Value 


The difftime() function returns the elapsed time in seconds from time1 to time2 as 
a double precision number. Type time_t is defined in <time.h>. 


Example that uses difftime() 
This example shows a timing application that uses difftime(). The example 


calculates how long, on average, it takes to find the prime numbers from 2 to 
10000. 
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#include <time.h> 
#include <stdio.h> 


#define RUNS 1000 
#define SIZE 10000 


int mark[SIZE]; 


int main(void) 

{ 
time_t start, finish; 
int i, loop, n, num; 


time(&start) ; 


/* This loop finds the prime numbers between 2 and SIZE */ 
for (loop = 0; loop < RUNS; ++loop) 
{ 
for (n = 0; n < SIZE; ++n) 
mark [n] = 0; 
/* This loops marks all the composite numbers with -1 */ 
for (num = 0, n = 2; n < SIZE; ++n) 
if ( ! mark[n]) 
{ 


for (i = 2 * n3 i < SIZE; i += n) 
mark[i] = -1; 
++num; 
} 
} 
time(&finish); 
printf("Program takes an average of %f seconds " 
"to find %d primes.\n", 
difftime(finish,start)/RUNS, num); 
} 


[KEKRKKERKEKERKEKRER EKER Output should be Similar:  *****KKKKKKKKKKKK 


The program takes an average of 0.106000 seconds to find 1229 primes. 
*/ 


Related Information 


div() — Calculate Quotient and Remainder 


Format 


70 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdlib.h> 
div_t div(int numerator, int denominator); 


Language Level: ANSI 


Thread Safe: YES. However, only the function version is thread safe. The macro 
version is NOT thread safe. 


Description 


The div() function calculates the quotient and remainder of the division of 
numerator by denominator. 


Return Value 


The div() function returns a structure of type div_t, containing both the quotient 
int quot and the remainder int rem. If the return value cannot be represented, its 
value is undefined. If denominator is 0, an exception will be raised. 


Example that uses div() 


This example uses div() to calculate the quotients and remainders for a set of two 
dividends and two divisors. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 
int num[2] {45,-45}; 
int den[2] = {7,-7}; 
div_t ans; /* div_t is a struct type containing two ints: 
‘quot' stores quotient; 'rem' stores remainder */ 


short i,j; 


printf("Results of division:\n"); 
for (i = 0; i < 2; i++) 
for (j = 0; j < 2; j++) 


ans = div(num[i],den[j]); 
printf("Dividend: %6d Divisor: %6d", num[i], den[j]); 
printf(" Quotient: %6d Remainder: %6d\n", ans.quot, ans.rem); 
} 
} 


[REKRKEEKREKERERERE Output Should be similar tO: *****KKKKKKKKKKKK 


Results of division: 

Dividend: 45 Divisor: 7 Quotient: 6 Remainder: 3 
Dividend: 45 Divisor: -7 Quotient: -6 Remainder: 3 
Dividend: -45 Divisor: 7 Quotient: -6 Remainder: -3 
Dividend: -45 Divisor: -7 Quotient: 6 Remainder: -3 


KA KKK AK KKK KKK KKK KEK KKK AKER IKKE AKIRA KKK AA AERA KKK | 


Related Information 
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erf() — erfc() — Calculate Error Functions 


Format 


#include <math.h> 
double erf(double x); 
double erfc(double x); 


Language Level: ILE C Extension 
Description 


The erf() function calculates the error function of: 


x 
an 2 edt 


0 


The erfc() function computes the value of 1.0 - erf(x). The erfc() function is used 
in place of erf() for large values of x. 


Return Value 


The erf() function returns a double value that represents the error function. The 
erfc() function returns a double value representing 1.0 - erf. 


Example that uses erf () 


This example uses erf() and erfc() to compute the error function of two 
numbers. 


#include <stdio.h> 
#include <math.h> 


double smallx, largex, value; 


int main(void) 


smallx = 0.13 
largex = 10.0; 
value = erf(smal1x); /* value = 0.112463 */ 


printf("Error value for 0.1: %1f\n", value); 


value = erfc(largex); /* value = 2.088488e-45 */ 
printf("Error value for 10.0: %le\n", value); 


} 


[KEKKRKKEREKEREKER Output should be similar tO: ****kKKKKKKKKKKKK 
Error value for 0.1: 0.112463 

Error value for 10.0: 2.088488e-45 

*/ 


Related Information 
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exit() — End Program 


Format 


#include <stdlib.h> 
void exit(int status); 


Language Level: ANSI 
Thread Safe: YES. 
Description 


The exit() function returns control to the host environment from the program. It 
first calls all functions that are registered with the atexit() function, in reverse 
order; that is, the last one that is registered is the first one called. It deletes all 
buffers and closes all open files before ending the program. 


The argument status can have a value from 0 to 255 inclusive, or be one of the 
macros EXIT SUCCESS or EXIT_FAILURE. A status value of EXIT_SUCCESS or 0 
indicates a normal exit; otherwise, another status value is returned. 


Note: When compiled with SYSIFCOPT(*ASYNCSIGNAL), exit() cannot be called 
in a signal handler. 


Return Value 


The exit() function returns both control and the value of status to the operating 
system. 


Example that uses exit () 


This example ends the program after deleting buffers and closing any open files if 
it cannot open the file myfile. 


#include <stdio.h> 
#include <stdlib.h> 


FILE «stream; 


int main(void) 
{ 
if ((stream = fopen("mylib/myfile", "r")) == NULL) 


perror("Could not open data file"); 
exit (EXIT_FAILURE) ; 
} 
} 


Related Information 


exp() — Calculate Exponential Function 


Format 
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#include <math.h> 
double exp(double x); 


Language Level: ANSI 
Description 


The exp() function calculates the exponential value of a floating-point argument x 
(e , where e equals 2.17128128...). 


Return Value 


If an overflow occurs, the exp() function returns HUGE_VAL. If an underflow 
occurs, it returns 0. Both overflow and underflow set errno to ERANGE. The value 
of errno may also be set to EDOM. 


Example that uses exp() 
This example calculates y as the exponential function of x: 


#include <math.h> 
#include <stdio.h> 


int main(void) 
double x, y; 


5.0; 
exp (x) 


X 
i 


printf("exp( %1f ) = %1f\n", x, y)s 
} 


[KEKRKRERERERERER Output should be similar tO: *****KKKKEKKKKKKK 


exp( 5.000000 ) = 148.413159 
*/ 


Related Information 


fabs() — Calculate Floating-Point Absolute Value 
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Format 

#include <math.h> 

double fabs(double x); 

Language Level: ANSI 

Description 

The fabs() function calculates the absolute value of the floating-point argument x. 


Return Value 


The fabs() function returns the absolute value. There is no error return value. 
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Example that uses fabs () 
This example calculates y as the absolute value of x: 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double x, y; 


Xx 
y 


-5.6798; 
fabs(x); 


printf("fabs( %1f ) = 21f\n", x, y); 
} 


[KERR KREKRKEKERERERERE Output should be similar tO: ****x*kKKKKKKKK 


fabs( -5.679800 ) = 5.679800 
*/ 


Related Information 


fclose() — Close Stream 


Format 


#include <stdio.h> 
int fclose(FILE *stream) ; 


Language Level: ANSI 

Thread Safe: YES 

Description 

The fclose() function closes a stream pointed to by stream. This function deletes 
all buffers that are associated with the stream before closing it. When it closes the 
stream, the function releases any buffers that the system reserved. When a binary 
stream is closed, the last record in the file is padded with null characters (\0) to 
the end of the record. 


Return Value 


The fclose() function returns 0 if it successfully closes the stream, or EOF if any 
errors were detected. 

The value of errno may be set to: 

Value Meaning 


ENOTOPEN 
The file is not open. 
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EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Note: The storage pointed to by the FILE pointer is freed by the fclose() function. 
After the use of the fclose() function, any attempt to use the FILE pointer 
is not valid. 


Example that uses fclose() 

This example opens a file myfile for reading as a stream; then it closes this file. 
#include <stdio.h> 

#define NUM_ALPHA 26 

int main(void) 


FILE *stream; 
char buffer[NUM_ALPHA] ; 


if (( stream = fopen("mylib/myfile", "r"))!= NULL ) 
fread( buffer, sizeof( char ), NUM ALPHA, stream ); 
printf( "buffer = %s\n", buffer ); 


if (fclose(stream)) /* Close the stream. */ 
perror("fclose error"); 
else printf("File mylib/myfile closed successfully.\n"); 


} 


Related Information 


fdopen() — Associates Stream With File Descriptor 


Format 


#include <stdio.h> 
FILE *fdopen(int handle, char *type); 


Language Level: XPG4 
Thread Safe: YES 
Description 


The fdopen() function is made available by specifying SYSIFCOPT(*IFSIO) on the 
compilation command. 


The fdopen() function associates an input or output stream with the file that is 
identified by handle. The type variable is a character string specifying the type of 
access that is requested for the stream. 


Mode Description 
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r Create a stream to read a text file. The file pointer is set to the beginning of 


the file. 

w Create a stream to write to a text file. The file pointer is set to the 
beginning of the file. 

a Create a stream to write, in append mode, at the end of the text file. The 
file pointer is set to the end of the file. 

I+ Create a stream for reading and writing a text file. The file pointer is set to 
the beginning of the file. 

wt Create a stream for reading and writing a text file. The file pointer is set to 
the beginning of the file. 

a+ Create a stream for reading or writing, in append mode, at the end of the 
text file. The file pointer is set to the end of the file. 

tb Create a stream to read a binary file. The file pointer is set to the beginning 
of the file. 

wb Create a stream to write to a binary file. The file pointer is set to the 


beginning of the file. 


ab Create a stream to write to a binary file in append mode. The file pointer 
is set to the end of the file. 


r+b or rb+ 
Create a stream for reading and writing a binary file. The file pointer is set 
to the beginning of the file. 


w+b or wb+ 
Create a stream for reading and writing a binary file. The file pointer is set 
to the beginning of the file. 


a+b or ab+ 
Create a stream for reading and writing to a binary file in append mode. 
The file pointer is set to the end of the file. 


Note: Use the w, w+, wb, wb+, and w+b modes with care; they can destroy 
existing files. 


The specified type must be compatible with the access method you used to open 
the file. If the file was opened with the O_LAPPEND flag, the stream mode must be 
a, at, ab, a+b, or ab+. To use the fdopen() function you need a file descriptor. To 
get a descriptor use the POSIX function open(). The O_APPEND flag is a mode for 
open(). Modes for open() are defined in QSYSINC/H/FCNTL. For further 
information see the topic. 


If fdopen() returns NULL, use close() to close the file. If fdopen() is successful, 
you must use fclose() to close the stream and file. 


Return Value 


The fdopen() function returns a pointer to a file structure that can be used to 
access the open file. A NULL pointer return value indicates an error. 


Example that uses fdopen() 
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This example opens the file sample.dat and associates a stream with the file using 
fdopen(). It then reads from the stream into the buffer. 


/* compile with SYSIFCOPT(*IFSIO) »/ 
#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 

#include <string.h> 


int main(void) 


{ 
long length; 
int fh; 
char buffer[20]; 
FILE *fp; 
printf("\nCreating sample.dat.\n"); 
if ((fp= fopen("/sample.dat", "w")) == NULL) { 
perror(" File was not created: "); 
exit(1); 
} 
fputs("Sample Program", fp); 
fclose(fp); 
memset(buffer, '\O', 20); /* Initialize buffer«/ 
if (-1 == (fh = open("/sample.dat", O RDWR|O_APPEND))) { 
perror("Unable to open sample.dat"); 
exit(1); 
} 
if (NULL == (fp = fdopen(fh, "r"))) { 
perror("fdopen failed"); 
close(fh); 
exit(1); 
} 
if (14 != fread(buffer, 1, 14, fp)) { 
perror("fread failed"); 
fclose(fp); 
exit(1); 
printf("Successfully read from the stream the following:\n%s.\n", buffer); 
fclose(fp); 
return 1; 
[BRK AK KEK KK EA KK ERK KEK KER AREA KEI KK EAR IK KEIRA KEKE KAIRIE 
* The output should be: 
* 
* Creating sample.dat. 
* Successfully read from the stream the following: 
* Sample Program. 
x/ 
} 


Related Information 


od O10.) On Da ee 
* open - See the [Api topic 
* close - See the [API topic 
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feof() — Test End-of-File Indicator 


Format 

#include <stdio.h> 

int feof(FILE *stream) ; 
Language Level: ANSI 


Description 


The feof() function indicates whether the end-of-file flag is set for the given 


stream. The end-of-file flag is set by several functions to indicate the end of the file. 


The end-of-file flag is cleared by calling the rewind(), fsetpos(), fseek(), or 
clearerr() functions for this stream. 


Return Value 


The feof() function returns a nonzero value if and only if the EOF flag is set; 
otherwise, it returns 0. 


Example that uses feof () 
This example scans the input stream until it reads an end-of-file character. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


char string[100]; 

FILE «stream; 

memset(string, 0, sizeof(string)); 

stream = fopen("qcpple/qacsrc(feof)", "r"); 


fscanf(stream, "%s", string); 

while (!feof(stream) ) 

{ 
printf("%s\n", string); 
memset(string, 0, sizeof(string)); 
fscanf(stream, "%s", string); 

} 

} 


Related Information 


ferror() — Test for Read/Write Errors 


Format 
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#include <stdio.h> 
int ferror(FILE *stream) ; 


Language Level: ANSI 
Description 


The ferror() function tests for an error in reading from or writing to the given 
stream. If an error occurs, the error indicator for the stream remains set until you 
close stream, call the rewind() function, or call the clearerr() function. 


Return Value 


The ferror() function returns a nonzero value to indicate an error on the given 
stream. A return value of 0 means that no error has occurred. 


Example that uses ferror() 


This example puts data out to a stream, and then checks that a write error has not 
occurred. 


#include <stdio.h> 
int main(void) 


FILE *stream; 
char *string = "Important information"; 
stream = fopen("mylib/myfile","w"); 


fprintf(stream, "%s\n", string); 
if (ferror(stream) ) 
{ 
printf("write error\n"); 
clearerr(stream) ; 


if (fclose(stream) ) 


perror("fclose error"); 


} 


Related Information 


fflush() — Write Buffer to File 


Format 

#include <stdio.h> 

int fflush(FILE *stream) ; 
Language Level: ANSI 


Thread Safe: YES 
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Description 


The fflush() function causes the system to empty the buffer that is associated 
with the specified output stream, if possible. If the stream is open for input, the 
fflush() function undoes the effect of any ungetc() function. The stream remains 
open after the call. 


If stream is NULL, the system flushes all open streams. 


Note: The system automatically deletes buffers when you close the stream, or 
when a program ends normally without closing the stream. 


Return Value 


The fflush() function returns the value 0 if it successfully deletes the buffer. It 
returns EOF if an error occurs. 

The value of errno may be set to: 

Value Meaning 


ENOTOPEN 
The file is not open. 


ERECIO 
The file is opened for record I/O. 


ESTDIN 
stdin cannot be opened. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


The fflush() function is not supported for files that are opened with type=record. 
Example that uses fflush() 


This example deletes a stream buffer. 
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#include <stdio.h> 


int main(void) 
{ 
FILE «stream; 
int ch; 
unsigned int result = 0; 


stream = fopen("mylib/myfile", "r"); 

while ((ch = getc(stream)) != EOF && isdigit(ch)) 
result = result * 10 + ch - 'O'; 

if (ch != EOF) 
ungetc(ch,stream) ; 


fflush(stream) ; /* fflush undoes the effect of ungetc function 
x/ 
printf("The result is: %d\n", result); 
if ((ch = getc(stream)) != EOF) 
printf("The character is: %c\n", ch); 


} 


Related Information 


fgetc() — Read a Character 
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Format 
#include <stdio.h> 


int fgetc(FILE *stream); 
Language Level: ANSI 
Thread Safe: YES 


Description 


The fgetc() function reads a single unsigned character from the input stream at the 
current position and increases the associated file pointer, if any, so that it points to 
the next character. 


Note: The fgetc() function is identical to getcQ], but it is always defined as a 
function call; it is never replaced by a macro. 


Return Value 


The fgetc() function returns the character that is read as an integer. An EOF 
return value indicates an error or an end-of-file condition. Use the feof() or the 
ferror() function to determine whether the EOF value indicates an error or the 
end of the file. 


The value of errno may be set to: 


Value Meaning 
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EBADF 
The file pointer or descriptor is not valid. 


ENOTREAD 
The file is not open for read operations. 


EGETANDPUT 
An read operation that was not allowed occurred after a write operation. 


ERECIO 
The file is open for record I/O. 


ESTDIN 
stdin cannot be opened. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


The fgetc() function is not supported for files that are opened with type=record. 
Example that uses fgetc() 

This example gathers a line of input from a stream. 

#include <stdio.h> 

#define MAX_LEN 80 

int main(void) 

FILE «stream; 


char buffer[MAX_LEN + 1]; 
int i, ch; 


stream = fopen("mylib/myfile","r"); 


for (i = 0; (i < (sizeof(buffer)-1) && 
((ch = fgetc(stream)) != EOF) && (ch != '\n')); i++) 
buffer[i] = ch; 


buffer[i] = '\0'; 


if (fclose(stream) ) 
perror("fclose error"); 


printf("line: %s\n", buffer); 


} 


[KERR KKK KER KKK KK KKK KK AK KAKA KKK IKK KKK IKKE AK KA KK AKKKA AKER 
If FILENAME contains: one two three 
The output should be: 


line: one two three 
KKK KKK KKK KKK AK KKK KK KKK KKK KKK IKKE KK KAKA KKK KKK KK AKIRA KK EAR K KER AKER | 


Related Information 
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fgetpos() — Get File Position 
Format 
#include <stdio.h> 
int fgetpos(FILE «stream, fpos_t *pos); 
Language Level: ANSI 
Thread Safe: YES 
Description 
The fgetpos() function stores the current position of the file pointer that is 
associated with stream into the object pointed to by pos. The value pointed to by 
pos can be used later in a call to fsetpos() to reposition the stream. 


Return Value 


The fgetpos() function returns 0 if successful; on error, it returns nonzero and sets 
errno to a nonzero value. 


The value of errno may be set to: 


Value Meaning 


EBADF 

The file pointer or descriptor is not valid. 
EBADSEEK 

Bad offset for a seek operation. 
ENODEV 

Operation was attempted on a wrong device. 
ENOTOPEN 

The file is not open. 
ERECIO 

The file is open for record I/O. 
ESTDERR 

stderr cannot be opened. 
ESTDIN 

stdin cannot be opened. 
ESTDOUT 

stdout cannot be opened. 
EIOERROR 

A non-recoverable I/O error occurred. 
EITORECERR 


A recoverable I/O error occurred. 


The fgetpos() function is not supported for files that are opened with type=record. 
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Example that uses fgetpos() 


This example opens the file myfile for reading and stores the current file pointer 
position into the variable pos. 


#include <stdio.h> 
FILE «stream; 


int main(void) 
{ 
int retcode; 
fpos_t pos; 


stream = fopen("mylib/myfile", "rb"); 


/* The value returned by fgetpos can be used by fsetpos */ 
/* to set the file pointer if 'retcode' is 0 */ 


if ((retcode = fgetpos(stream, Point-of-Sale)) == 0) 
printf("Current position of file pointer found\n"); 
fclose(stream) ; 


} 


Related Information 


fgets() — Read a String 


Format 


#include <stdio.h> 
char *fgets (char *string, int n, FILE *stream); 


Language Level: ANSI 

Thread Safe: YES 

Description 

The fgets() function reads characters from the current stream position up to and 
including the first new-line character (\n), up to the end of the stream, or until the 
number of characters read is equal to n-1, whichever comes first. The fgets () 
function stores the result in string and adds a null character (\0) to the end of the 
string. The string includes the new-line character, if read. If n is equal to 1, the 
string is empty. 

The value of errno can be set to EBADF,(the catalog descriptor is not valid). 
Return Value 

The fgets() function returns a pointer to the string buffer if successful. A NULL 
return value indicates an error or an end-of-file condition. Use the feof() or 


ferror() functions to determine whether the NULL value indicates an error or the 
end of the file. In either case, the value of the string is unchanged. 
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The fgets() function is not supported for files that are opened with type=record. 
Example that uses fgets () 


This example gets a line of input from a data stream. The example reads no more 
than MAX_LEN - 1 characters, or up to a new-line character from the stream. 


#include <stdio.h> 
#define MAX_LEN 100 
int main(void) 
FILE «stream; 
char line[MAX_LEN], *result; 
stream = fopen("mylib/myfile","rb"); 


if ((result = fgets(line,MAX_LEN,stream)) != NULL) 
printf("The string is %s\n", result); 


if (fclose(stream) ) 


perror("fclose error"); 


} 


Related Information 


fgetwc() — Read Wide Character from Stream 
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Format 


#include <wchar.h> 
#include <stdio.h> 
wint_t fgetwc(FILE *stream) ; 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fgetwc() reads the next multibyte character from the input stream pointed to 
by stream, converts it to a wide character, and advances the associated file position 
indicator for the stream (if defined). 


Using non-wide-character functions with fgetwc() on the same stream results in 
undefined behavior. After calling fgetwc(), flush the buffer or reposition the 
stream pointer before calling a write function for the stream, unless EOF has been 
reached. After a write operation on the stream, flush the buffer or reposition the 
stream pointer before calling fgetwc(). 
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Note: 


The behavior of the fgetwc() function is affected by the LC_CTYPE category 
of the current locale. If you change the category between subsequent read 
operations on the same stream, undefined results can occur. 


This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The fgetwc() function returns the next wide character that corresponds to the 
multibyte character from the input stream pointed to by stream. If the stream is at 
EOF, the EOF indicator for the stream is set, and fgetwc() returns WEOF. 


If a read error occurs, the error indicator for the stream is set, and the fgetwc() 
function returns WEOF. If an encoding error occurs (an error converting the 
multibyte character into a wide character), the fgetwc() function sets errno to 
EILSEQO and returns WEOF. 


Use the ferror() and feof() functions to distinguish between a read error and an 
EOF. EOF is only reached when an attempt is made to read past the last byte of 
data. Reading up to and including the last byte of data does not turn on the EOF 
indicator. 


Example that uses fgetwc() 


This example opens a file, reads in each wide character, and prints out the 
characters. 


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 


int main(void) 


FILE *stream; 
wint_t wc; 


if (NULL == (stream = fopen("fgetwc.dat", "r"))) { 
printf("Unable to open: \"fgetwc.dat\"\n"); 
exit(1); 

} 


errno = 0; 
while (WEOF != (wc = fgetwc(stream) )) 
printf("we = %lc\n", wc); 


if (EILSEQ == errno) { 
printf("An invalid wide character was encountered.\n"); 
exit(1); 


fclose(stream) ; 
return 0; 


} 


* * x End of File * * * 


Related Information 
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fgetws() — Read Wide-Character String from Stream 


Format 


#include <wchar.h> 
#include <stdio.h> 
wchar_t *fgetws(wchar_t *wcs, int n, FILE *stream); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fgetws() function reads at most one less than the number of wide characters 
specified by n from the stream pointed to by stream. The fgetws () function stops 
reading characters after WEOF, or after it reads a new-line wide character (which is 
retained). It adds a null wide character immediately after the last wide character 
read into the array. The fgetws() function advances the file position unless there is 
an error. If an error occurs, the file position is undefined. 


Using non-wide-character functions with the fgetws() function on the same stream 
results in undefined behavior. After calling the fgetws() function, flush the buffer 
or reposition the stream pointer before calling a write function for the stream, 
unless WEOF has been reached. After a write operation on the stream, flush the 
buffer or reposition the stream pointer before calling the fgetws() function. 


Note: The behavior of the fgetws() function is affected by the LC_CTYPE category 
of the current locale. If you change the category between subsequent read 
operations on the same stream, undefined results can occur. 


Return Value 


If successful, the fgetws() function returns a pointer to the wide-character string 
wes. If WEOF is encountered before any wide characters have been read into wes, 
the contents of wes remain unchanged and the fgetws() function returns a null 
pointer. If WEOF is reached after data has already been read into the string buffer, 
the fgetws() function returns a pointer to the string buffer to indicate success. A 
subsequent call would return NULL because WEOF would be reached without any 
data being read. 


If a read error occurs, the contents of wes are indeterminate, and the fgetws () 
function returns NULL. If an encoding error occurs (in converting a wide character 
to a multibyte character), the fgetws() function sets errno to EILSEQ and returns 
NULL. 
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If n equals 1, the wes buffer has only room for the ending null character, and 
nothing is read from the stream. (Such an operation is still considered a read 
operation, so it cannot immediately follow a write operation unless the buffer is 
flushed or the stream pointer repositioned first.) If n is greater than 1, the fgetws() 
function fails only if an I/O error occurs, or if WEOF is reached before data is read 
from the stream. 


Use the ferror() and feof() functions to distinguish between a read error and a 
WEOF. A WEOF error is only reached when an attempt is made to read past the 
last byte of data. Reading up to and including the last byte of data does not turn 
on the WEOF indicator. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Example that uses fgetws() 
This example opens a file, reads in the file contents, then prints the file contents. 


#include <errno.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 


int main(void) 

{ 
FILE «stream; 
wchar_t wces[100]; 


if (NULL == (stream = fopen("fgetws.dat", "r"))) { 
printf("Unable to open: \"fgetws.dat\"\n"); 
exit(1); 

} 


errno = Q; 
if (NULL == fgetws(wcs, 100, stream)) { 
if (EILSEQ == errno) { 
printf("An invalid wide character was encountered.\n"); 
exit(1); 


else if (feof(stream) ) 
printf("End of file reached.\n"); 
else 
perror("Read error.\n"); 
} 
printf("wes = \"%1s\"\n", wes); 
fclose(stream) ; 
return 0; 


[RRR RK KKK KEIR KEK KKK KKK KKK KKK KKK KKK EAR KK KKK KEK KKK K ERA KK 
Assuming the file fgetws.dat contains: 


This test string should not return -1 
The output should be similar to: 
wes = "This test string should not return -1" 


KKK KKK KKK KKK AK KKK KKK KK KKK KKK KKK IKKE AK KKK KK AK KKK AKER AKER K | 


} 


Related Information 
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fileno() — Determine File Handle 


90 


Format 


#include <stdio.h> 
int fileno(FILE *stream) ; 


Language Level: XPG4 
Description 


The fileno() function only works in ILE C when the Integrated File System has 
been enabled. The fileno() function determines the file handle that is currently 
associated with stream. 


The value of errno can be set to EBADF. 
Return Value 


If the environment variable QIBM_USE_DESCRIPTOR_STDIO is set to Yes, the 
fileno()function returns 0 for stdin, 1 for stdout, and 2 for stderr. 


With OQIBM_USE_DESCRIPTOR_STDIO set to No, the ILE C session files stdin, 
stdout, and stderr do not have a file descriptor associated with them. The 
fileno() function will return a value of -1 in this case. 


Example that uses fileno() 
This example determines the file handle of the stderr data stream. 


/* Compile with SYSIFCOPT(*IFSIO) */ 
#include <stdio.h> 


int main (void) 
{ 
FILE «fp; 
int result; 


fp = fopen ("stderr","w"); 


result = fileno(fp); 
printf("The file handle associated with stderr is %d.\n", result); 
return 0; 


[BRK RK KEK KK ERK AKER IKEA KKK KAKA KEKE KIA IKEA KK E IKKE ARK 


* The output should be: 


* 


* The file handle associated with stderr is -1. 
KR KIRA KKK A KKK KKK KAKI KK KKK KKK AKIRA KKK KKK KKK AKA KIER K KER AK KEK | 


} 


Related Information 
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floor() —Find Integer <=Argument 


Format 

#include <math.h> 

double floor(double x); 

Language Level: ANSI 

Description 

The floor() function calculates the largest integer that is less than or equal to x. 
Return Value 

The floor() function returns the floating-point result as a double value. 

The result of floor() cannot have a range error. 


Example that uses floor() 


This example assigns y value of the largest integer less than or equal to 2.8 and z 
the value of the largest integer less than or equal to -2.8. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double y, Z; 


floor(2.8); 
floor(-2.8); 


» 
z 


printf("floor( 2.8) = %1f\n", y); 
printf("floor( -2.8 ) = %1f\n", z); 
} 


[REKRKERKKEKERERERKERE Output should be similar tO: ******KKKKKKKKK 
floor( 2.8 ) = 2.000000 

floor( -2.8 ) = -3.000000 

*/ 


fmod() — Calculate Floating-Point Remainder 


Format 


#include <math.h> 
double fmod(double x, double y); 


Language Level: ANSI 
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Description 


The fmod() function calculates the floating-point remainder of x/y. The absolute 
value of the result is always less than the absolute value of y. The result will have 
the same sign as x. 


Return Value 


The fmod() function returns the floating-point remainder of x/y. If y is zero or if 
x/y causes an overflow, fmod() returns 0. The value of errno may be set to EDOM. 


Example that uses fmod() 


This example computes z as the remainder of x/y; here, x/y is -3 with a remainder 
of -1. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 


double x, y, Z3 


x = -10.0; 
y = 3.0; 
z = fmod(x,y)3 /* z = -1.0 */ 


printf("fmod( %1f, %1f) = %1f\n", x, y, Z)3 
} 


[EKRKKERKEKEREKERERE Output should be similar tO: ***k**kkKKKKEKKK 


fmod( -10.000000, 3.000000) = -1.000000 
*/ 


Related Information 


fopen() — Open Files 
Format 
#include <stdio.h> 
FILE *fopen(const char *filename, const char *mode); 
Language Level: ANSI 
Thread Safe: YES 
Description 
The fopen() function opens the file that is specified by filename. The mode 
parameter is a character string specifying the type of access that is requested for 


the file. The mode variable contains one positional parameter followed by optional 
keyword parameters. 
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Note: Because the fopen() API calls the open() API, the owner of the file is given 
read, write, and execute authority to the file. 


The possible values for the positional parameters are: 


Mode Description 


r Open a text file for reading. The file must exist. 

w Create a text file for writing. If the given file exists, its contents are 
destroyed unless it is a logical file. 

a Open a text file in append mode for writing at the end of the file. The 
fopen() function creates the file if it does not exist and is not a logical file. 

I+ Open a text file for both reading and writing. The file must exist. 

wt Create a text file for both reading and writing. If the given file exists, its 
contents are cleared unless it is a logical file. 

a+ Open a text file in append mode for reading or updating at the end of the 
file. The fopen() function creates the file if it does not exist. 

rb Open a binary file for reading. The file must exist. 

wb Create an empty binary file for writing. If the file exists, its contents are 


cleared unless it is a logical file. 


ab Open a binary file in append mode for writing at the end of the file. The 
fopen function creates the file if it does not exist. 


r+b or rb+ 
Open a binary file for both reading and writing. The file must exist. 


w+b or wb+ 
Create an empty binary file for both reading and writing. If the file exists, 
its contents will be cleared unless it is a logical file. 


a+b or ab+ 
Open a binary file in append mode for writing at the end of the file. The 
fopen() function creates the file if it does not exist. 


The fopen() function is not supported for files that are opened with the attributes 
type=record and ab+, rb+, or wb+. 


Note: Use the w, w+, wb, w+b, and wb+ parameters with care; data in existing 
files of the same name will be lost. 
Text files contain printable characters and control characters that are organized into 
lines. Each line ends with a new-line character, except possibly the last line, 
depending on the compiler. The system may insert or convert control characters in 
an output text stream. The fopen() function mode "a" and "a+" can not be used for 
the QSYS.LIB file system. There are implementation restrictions when using the 
QSYS.LIB file system for text files in all modes. Seeking beyond the start of files 
cannot be relied on to work with streams opened in text mode. 


If a binary file does not exist, you can create one using the following command: 


CRTSRCPF FILE(MYLIB/MYFILE) RCDLEN(LRECL) MBR(MYMBR) 
SYSTEM(*FILETYPE) 


Note: Data output to a text stream may not compare as equal to the same data on 
input. The QSYS.LIB file system treats database files as a directory of 
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members. The database file must exist before a member can be dynamically 
created when using the fopen() function. 


The Integrated File System supports files of up to 4GB in size. There are three 
methods you can use to allow your application programs access to 64-bit C 
runtime functions for IFS files larger than 2 gigabytes: 


* Specify SYSIFCOPT(*IFS64IO) on a compilation command, which causes the 
native C compiler to define _IFS64_IO_. This causes the macros _LARGE_FILES 
and _LARGE_FILE_API to be defined. 


* Define the macro _LARGE_FILES, either in the program source or by specifying 
DEFINE(’_LARGE_FILES’) on a compilation command. The existing C runtime 
functions and the relevant data types in the code will all be automatically 
mapped or redefined to their 64-bit versions. 


* Define the macro _LARGE_FILE_API, either in the program source or by 
specifying DEFINE(’_LARGE_FILE_API’) on a compilation command. This 
makes visible the set of of new 64-bit C runtime functions and data types. The 
application must explicitly specify the name of the C runtime functions, both 
existing version and 64-bit version, to use. 


The 64-bit C runtime functions include the following: int fgetpos64(), FILE 
*fopen64(), FILE *freopen64(), FILE «wfopen64(), int fsetpos64(FILE *, const 
fpost64_t *), FILE «tmpfile64(), int fseeko(FILE *, off_t, int), int 
fseeko64(FILE *, of f64_t, int), off_t ftello(FILE *), and of f64_t ftell064(). 


Binary files contain a series of characters. For binary files, the system does not 
translate control characters on input or output. 


If a text file does not exist, you can create one using the following command: 


CRTPF FILE(MYLIB/MYFILE) RCDLEN(LRECL) MBR(MYMBR) 
MAXMBRS(*NOMAX) SYSTEM(*FILETYPE) 


When you open a file with a, a+, ab, a+b or ab+ mode, all write operations take 
place at the end of the file. Although you can reposition the file pointer using the 
fseek() function or the rewind() function, the write functions move the file pointer 
back to the end of the file before they carry out any operation. This action prevents 
you from overwriting existing data. 


When you specify the update mode (using + in the second or third position), you 
can both read from and write to the file. However, when switching between 
reading and writing, you must include an intervening positioning function such as 
the fseek(), fsetpos(), rewind(), or fflush(). Output may immediately follow 
input if the end-of-file was detected. 


Keyword parameters for non-Integrated File System 


blksize=value 
Specifies the maximum length, in bytes, of a physical block of records. 


Irecl=value 
Specifies the length, in bytes, for fixed-length records and the maximum 
length for variable-length records. 


recfm=value 
value can be: 


F fixed-length, deblocked records 
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FB fixed-length, blocked records 

Vv variable-length, deblocked records 

VB variable-length, blocked records 

VBS __ variable-length, blocked, spanned records for tape files 
VS variable-length, deblocked, spanned records for tape files 


D variable-length, deblocked, unspanned records for ASCII D format 
for tape files 


DB variable-length, blocked, unspanned records for ASCII D format for 


tape files 

U undefined format for tape files 

FA fixed-length that uses first character forms control data for printer 
files 


Note: If the file is created using CTLCHAR(*FCFC), the first character 
form control will be used. If it is created using CTLCHAR(*NONE), 
the first character form control will not be used. 


commit=value 
value can be: 


N This parameter identifies that this file is not opened under commitment 
control. This is the default. 


Y This parameter identifies that this file is opened under commitment 
control. 


ccsid=value 
If a CCSID that is not supported by the iSeries is specified, it is ignored by 
data management. The default is the job’s CCSID value. 


arrseq=value 
value can be: 


N This parameter identifies that this file is processed in the way it was 
created. This is the default. 


Y This parameter identifies that this file is processed in arrival sequence. 


indicators=value 
value can be: 


N This parameter identifies that indicators in display, ICF, or printer files 
are stored in the file buffer. This is the default. 


Y This parameter identifies that indicators in display, ICF, or printer files 
are stored in a separate indicator area, not in the file buffer. A file buffer is 
the area the iSeries system uses to transfer data to and from the user 
program and the operating system when writing and reading. You must 
store indicators in a separate indicator area when processing ICF files. 


type=value 
value can be: 


memory This parameter identifies this file as a memory file that is 
accessible only from C programs. This is the default. 


record This parameter specifies that the file is to be opened for sequential 
record I/O. The file must be opened as a binary file; otherwise, the 
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fopen() function fails. Read and write operations are done with the 
fread() function and the fwrite() functions. 


Keyword parameters for Integrated File System only 
type=value 


value can be: 


record The file is opened for sequential record I/O. (File has to be opened 
as binary stream.) 


ccsid=value 


ccsid is converted to a code page value. The default is to use the job CCSID 
value as the code page. The CCSID and codepage option cannot both be 
specified. The CCSID option provides compatibility with iSeries and Data 
management based stream I/O. 


Note: Mixed data (the data contains both single and double-byte 
characters) is not supported for a file data processing mode of text. 
Mixed data is supported for a file processing mode of binary. 


If you specify the ccsid keyword, you cannot specify the o_ccsid keyword 
or the codepage keyword. 


Because of the possible expansion or contraction of converted data, making 
assumptions about data size and the current file offset is dangerous. For 
example, a file might have a physical size of 100 bytes, but after an 
application has read 100 bytes from the file, the current file offset may be 
only 50. In order to read the whole file, the application might have to read 
200 bytes or more, depending on the CCSIDs involved. Therefore, file 
positioning functions such as ftel1(), fseek(), fgetpos(), and fsetpos() 
will not work. These functions will fail with ENOTSUP. Read functions 
also will not work if buffering is on, as it is by default. To turn buffering 
off, use the setvbuf function with the IONBF keyword. 


The fopen() function will fail with the ECONVERT error when all of the 
following three conditions occur: 


* The file data processing mode is text. 
* The code page is not specified. 


* The CCSID of the job is ‘mixed-data’ (the data contains both single- and 
double—byte characters). 


o_ccsid=value 


This parameter is similar to the ccsid parameter, except that the value 
specified is not converted to a code page. Also, mixed data is supported. If 
the file is created, it is tagged with the specified CCSID. If the file already 
exists, data will be converted from the CCSID of the file to the specified 
CCSID on read operations. On write operations, the data is assumed to be 
in the specified CCSID, and is converted to the CCSID of the file. 


Because of the possible expansion or contraction of converted data, making 
assumptions about data size and the current file offset is dangerous. For 
example, a file might have a physical size of 100 bytes, but after an 
application has read 100 bytes from the file, the current file offset may be 
only 50. In order to read the whole file, the application might have to read 
200 bytes or more, depending on the CCSIDs involved. Therefore, file 
positioning functions such as ftel1(), fseek(), fgetpos(), and fsetpos() 
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will not work. These functions will fail with ENOTSUP. Read functions 
also will not work if buffering is on, as it is by default. To turn buffering 
off, use the setvbuf function with the IONBF keyword. 


Example that uses o_ccsid 

/* Create a file that is tagged with CCSID 37 x/ 

if ((fp = fopen("/MYFILE" , "w, o _ccsid=37")) == NULL) { 
printf("Failed to open file with o_ccsid=37\n"); 

} 


fclose(fp); 


/* Now reopen the file with CCSID 13488, because your application 
wants to deal with the data in UNICODE «/ 


if ((fp = fopen("/MYFILE" , "r+, o_ccsid=13488")) == NULL) { 
printf("Failed to open file with o_ccsid=13488\n"); 


/* Turn buffering off because read functions do not work when 
buffering is on */ 


if (setbuf(fp, NULL, _IONBF, 0) != 0){ 
printf("Unable to turn buffering off\n"); 
} 


/* Because you opened with o_ccsid = 13488, you must provide 
all input data as unicode. 

If this program is compiled with LOCALETYPE(*LOCALEUCS2) , 

L constrants will be unicode. */ 


funcreturn = fputws(L"ABC", fp); /* Write a unicode ABC to the file. */ 


if (funcreturn < 0) { 
printf("Error with 'fputws' on line %d\n", __LINE_); 
} 


/* Because the file was tagged with CCSID 37, the unicode ABC was 
converted to EBCDIC ABC when it was written to the file. */ 


codepage=value 
The code page that is specified by value is used. 


If you specify the codepage keyword, you cannot specify the ccsid 
keyword or the o_ccsid keyword. 


If the file to be opened does not exist, and the open mode specifies that the 
file should be created, the file is created and tagged with the calculated 
code page. If the file already exists, the data read from the file is converted 
from the files code page to the calculated code page during the read 
operation. Data written to the file is assumed to be in the calculated code 
page and is converted to the code page of the file during the write 
operation. 


crln=value 
value can be: 


Y The line terminator to be used is carriage return [CR], new line [NL] 
combination. When data is read, all carriage returns [CR] are stripped for 
string functions. When data is written to a file, carriage returns [CR] are 
added before each new line [NL] character. Line terminator processing only 
occurs when a file is open with text mode. This is the default. 


N The line terminator to be used is new line [NL] only. 


The keyword parameters are not case sensitive and should be separated by a 
comma. 
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The fopen() function generally fails if parameters are mismatched. 
Return Value 


The fopen() function returns a pointer to a FILE structure type that can be used to 
access the open file. 


Note: To use stream files (type = record) with record I/O functions, you must cast 
the FILE pointer to an RFILE pointer. 


A NULL pointer return value indicates an error. 


The value of errno may be set to: 
Value Meaning 


EBADMODE 
The file mode that is specified is not valid. 


EBADNAME 
The file name that is specified is not valid. 


ECONVRT 
Conversion error. 


ENOENT 
No file or library. 


ENOMEM 
Storage allocation request failed. 


ENOTOPEN 
The file is not open. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


If the mode string passed to fopen() is correct, fopen() will not set errno to 
EBADMODE, regardless of the file type. 


If the mode string that is passed to fopen() is not valid, fopen() will set errno to 
EBADMODE, regardless of the file type. 


If the mode string passed to fopen() is correct, but is invalid to that specific type 
of file, fopen() will set errno to ENOTOPEN, EIOERROR, or EIORECERR, 
regardless of the file type. 

Example that uses fopen() 


This example attempts to open a file for reading. 
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#include <stdio.h> 
#define MAX_LEN 60 


int main(void) 
{ 
FILE «stream; 
fpos_t pos; 
char linel[MAX_LEN]; 
char line2[MAX_LEN] ; 
char *results; 
char ch; 
int num; 


/* The following call opens a text file for reading. */ 
if ((stream = fopen("mylib/myfile", "r")) == NULL) 
printf("Could not open data file\n"); 
else if ((result = fgets(linel,MAX_LEN,stream)) != NULL) 
{ 
printf("The string read from myfile: %s\n", result); 
fclose(stream) ; 


} 


/* The following call opens a fixed record length file «/ 
/* for reading and writing. */ 
if ((stream = fopen("mylib/myfile2", "rb+, lrecl=80, \ 
blksize=240, recfm=f")) == NULL) 
printf("Could not open data file\n"); 
else { 
fgetpos(stream, Point-of-Sale); 
if (!fread(line2,sizeof(line2),1,stream) ) 
perror("fread error"); 
else printf("lst record read from myfile2: %s\n", line2); 


fsetpos(stream, Point-of-Sale); /* Reset pointer to start of file */ 
fputs(result, stream); /* The line read from myfile is +*/ 
/* written to myfile2. */ 


fclose(stream) ; 
} 


Related Information 


* open() API in the [information Center API topic] 
fprintf() — Write Formatted Data to a Stream 


Format 


#include <stdio.h> 
int fprintf(FILE «stream, const char *format-string, argument-list); 


Language Level: ANSI 
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Thread Safe: YES 
Description 


The fprintf() function formats and writes a series of characters and values to the 
output stream. The fprintf() function converts each entry in argument-list, if any, 
and writes to the stream according to the corresponding format specification in the 
format-string. 


The format-string has the same form and function as the format-string argument for 
the printf() function. 


Return Value 


The fprintf() function returns the number of bytes that are printed or a negative 
value if an output error occurs. 


Example that uses fprintf() 


This example sends a line of asterisks for each integer in the array count to the file 
myfile. The number of asterisks that are printed on each line corresponds to an 
integer in the array. 


#include <stdio.h> 
int count [10] = {1, 5, 8, 3, 0, 3, 5, 6, 8, 10}; 
int main(void) 


int i,j; 
FILE «stream; 


stream = fopen("mylib/myfile", "w"); 

/* Open the stream for writing */ 
for (i=0; i < sizeof(count) / sizeof(count[0]); i++) 
{ 

for (j = 0; j < count[i]; j++) 
fprintf(stream,"*"); 


/* Print asterisk */ 
fprintf(stream,"\n") ; 
/* Move to the next line */ 


fclose (stream); 


} 


[KEKRKKERKEKERKEKERERE Output should be similar tO: ***kx*kKKKKKEKKK 


* 
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*/ 


Related Information 
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fputc() — Write Character 


Format 


#include <stdio.h> 
int fputc(int c, FILE *stream); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fputc() function converts c to an unsigned char and then writes c to the 
output stream at the current position and advances the file position appropriately. If 
the stream is opened with one of the append modes, the character is appended to 
the end of the stream. 


The fputc() function is identical to putc(); it always is defined as a function call; 
it is never replaced by a macro. 


Return Value 


The fputc() function returns the character that is written. A return value of EOF 
indicates an error. 


The value of errno may be set to: 
Value Meaning 


ENOTWRITE 
The file is not open for write operations. 


EPUTANDGET 
A write operation that was not permitted occurred after a read operation. 


ERECIO 
The file is open for record I/O. 


ESTDERR 
stderr cannot be opened. 


ESTDOUT 
stdout cannot be opened. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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The fputc() function is not supported for files that are opened with type=record. 
Example that uses fputc() 
This example writes the contents of buffer to a file that is called myfile. 


Note: Because the output occurs as a side effect within the second expression of 
the for statement, the statement body is null. 


#include <stdio.h> 
#define NUM ALPHA 26 


int main(void) 

{ 
FILE * stream; 
int i; 
int ch; 


char buffer[NUM_ALPHA + 1] = "“abcdefghijklmnopqrstuvwxyz"s 
if (( stream = fopen("mylib/myfile", "w"))!= NULL ) 
{ 


/* Put buffer into file */ 
for (i = 0; (i < sizeof(buffer) ) && 
((ch = fputc( buffer[i], stream)) != EOF ); ++i ); 
fclose( stream ); 
} 
else 
perror( "Error opening myfile" ); 


} 


Related Information 


_fputchar - Write Character 
Format 
#include <stdio.h> 
int _fputchar(int c); 
Note: The _fputchar function is supported only for C++, not for C. 
Language Level: Extension 


Description 


_fputchar writes the single character c to the stdout stream at the current position. 
It is equivalent to the following fpute call: 


fputc(c, stdout); 


For portability, use the ANSI/ISO fputc function instead of _fputchar. 


Return Value 
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_fputchar returns the character written. A return value of EOF indicates that a write 
error has occurred. Use ferror and feof to tell whether this is an error condition 
or the end of the file. 


Example that uses _fputchar() 


This example writes the contents of buffer to stdout: 


#include <stdio.h> 
int main(void) 
{ 
char buffer[80]; 
int i,ch = 1; 
for (i = 0; i < 80; i++) 
buffer[i] = 'c'; 
for (i = 0; (i < 80) && (ch != EOF); i++) 
ch = _fputchar(buffer[i]); 
printf("\n"); 
return 0; 


} 


The output should be similar to: 


CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 


Related Information: 


fputs() — Write String 


Format 
#include <stdio.h> 


int fputs(const char «string, FILE *stream); 
Language Level: ANSI 
Thread Safe: YES 


Description 


The fputs() function copies string to the output stream at the current position. It 
does not copy the null character (\0) at the end of the string. 


Return Value 


The fputs() function returns EOF if an error occurs; otherwise, it returns a 
non-negative value. 

The value of errno may be set to: 

Value Meaning 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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EPUTANDGET 
A write operation that was not permitted occurred after a read operation. 


The fputs() function is not supported for files that are opened with type=record. 
Example that uses fputs() 
This example writes a string to a stream. 


#include <stdio.h> 
#define NUM ALPHA 26 
int main(void) 


FILE * stream; 
int num; 


/* Do not forget that the '\@' char occupies one character */ 
static char buffer[NUM_ALPHA + 1] = "“abcdefghijkImnopqrstuvwxyz"; 


if ((stream = fopen("mylib/myfile", "w")) != NULL ) 
{ 


/* Put buffer into file */ 
if ( (num = fputs( buffer, stream )) != EOF ) 
{ 
/* Note that fputs() does not copy the \@ character «/ 
printf( "Total number of characters written to file = %i\n", num ); 
fclose( stream ); 
} 
else /* fputs failed «/ 
perror( "fputs failed" ); 


else 
perror( "Error opening myfile" ); 
} 


Related Information 


fputwc() — Write Wide Character 


Format 


#include <wchar.h> 
#include <stdio.h> 
wint_t fputwc(wint_t wc, FILE *stream) ; 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fputwc() function converts the wide character we to a multibyte character and 
writes it to the output stream pointed to by stream at the current position. It also 
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advances the file position indicator appropriately. If the file cannot support 
positioning requests, or if the stream was opened with append mode, the character 
is appended to the stream. 


Using non-wide-character functions with the fputwc () function on the same stream 
will result in undefined behavior. After calling the fputwc() function, delete the 
buffer or reposition the stream pointer before calling a read function for the stream. 
After reading from the stream, delete the buffer or reposition the stream pointer 
before calling the fputwc() function, unless EOF has been reached. 


Note: The behavior of the fputwc() function is affected by the LC_CTYPE category 
of the current locale. If you change the category between subsequent 
operations on the same stream, undefined results can occur. This function is 
available when SYSIFCOPT(*IFSIO) and LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) are specified on the compilation command. 


Return Value 

The fputwc() function returns the wide character that is written. If a write error 
occurs, the error indicator for the stream is set, and the fputwc() function returns 
WEOEF. If an encoding error occurs during conversion from wide character to a 
multibyte character, fputwc() sets errno to EILSEQ and returns WEOF. 

Example that uses fputwc() 


This example opens a file and uses the fputwc() function to write wide characters 
to the file. 
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#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 


int main(void) 

{ 
FILE «stream; 
wchar_t *wcs = L"A character string."; 
int as 


if (NULL == (stream = fopen("fputwc.out", "w"))) 


{ 
printf("Unable to open: \"fputwc.out\".\n"); 
exit(1); 

} 

for (i = 0; wes[i] != L'\O's i++) { 
errno = 0; 


if (WEOF == fputwc(wcs[i], stream)) { 
printf("Unable to fputwc() the wide character. \n" 
"wes[%d] = 0x%.41x\n", i, wes[i]); 
if (EILSEQ == errno) 
printf("An invalid wide character was encountered. \n"); 
exit(1); 


fclose(stream) ; 
return 0; 


[BRK AK KERR KEIR KER AKER IKEA KKK AK KEI KKK KEKE KKK ER AKER 
The output file fputwc.out should contain: 


A character string. 


KKK KA KKK KKK KA KKK KKK A KKK A KKK IKKE IKKE AK KEKE KIA IKE RARER KER | 


} 


Related Information 


fputws() — Write Wide-Character String 


Format 


#include <wchar.h> 
#include <stdio.h> 
int fputws(const wchar_t *wcs, FILE *stream); 


Language Level: XPG4 
Thread Safe: YES. 


Description 
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The fputws() function converts the wide-character string wes to a 
multibyte-character string and writes it to stream as a multibyte-character string. It 
does not write the ending null wide character. 


Using non-wide-character functions with the fputws () function on the same stream 
will result in undefined behavior. After calling the fputws() function, flush the 
buffer or reposition the stream pointer before calling a read function for the stream. 
After a read operation, flush the buffer or reposition the stream pointer before 
calling the fputws() function, unless EOF has been reached. 


Note: The behavior of the fputws() function is affected by the LC_CTYPE category 
of the current locale. If you change the category between subsequent 
operations on the same stream, undefined results can occur. This function is 
available when SYSIFCOPT(*IFSIO) and LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) are specified on the compilation command. 


Return Value 


The fputws() function returns a non-negative value if successful. If a write error 
occurs, the error indicator for the stream is set, and the fputws() function returns 
-1. If an encoding error occurs in converting the wide characters to multibyte 
characters, the fputws() function sets errno to EILSEQ and returns -1. 


Example that uses fputws() 


This example opens a file and writes a wide-character string to the file using the 
fgetws() function. 


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 


int main(void) 


{ 
FILE «stream; 
wchar_t *«wcs = L"This test string should not return -1"; 


if (NULL == (stream = fopen("fputws.out", "w"))) { 
printf("Unable to open: \"fputws.out\".\n"); 
exit(1); 

} 

errno = Q; 


if (EOF == fputws(wcs, stream)) { 
printf("Unable to complete fputws() function.\n"); 
if (EILSEQ == errno) 
printf("An invalid wide character was encountered. \n"); 
exit(1); 


fclose(stream) ; 
return 0; 


[BERR KR EA KK AK KEKE KERIKERI KEK KK EAR KKK KAKI A AERA 
The output file fputws.out should contain: 


This test string should not return -1 
KKK KKK KKK KK EAR KEIR KKK KKK KKK AKER AK KEI KK AKKKAA KEKE ER EKERKK | 


} 


Related Information 
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fread() — Read Items 
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Format 


#include <stdio.h> 
size_t fread(void *buffer, size_t size, size_t count, FILE *stream); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fread() function reads up to count items of size length from the input stream 
and stores them in the given buffer. The position in the file increases by the number 
of bytes read. 


Return Value 


The fread() function returns the number of full items successfully read, which can 
be less than count if an error occurs, or if the end-of-file is met before reaching 
count. If size or count is 0, the fread() function returns zero, and the contents of the 
array and the state of the stream remain unchanged. 


The value of errno may be set to: 
Value Meaning 


EGETANDPUT 
A read operation that was not permitted occurred after a write operation. 


ENOREC 
Record is not found. 


ENOTREAD 
The file is not open for read operations. 


ERECIO 
The file is open for record I/O. 


ESTDIN 
stdin cannot be opened. 


ETRUNC 
Truncation occurred on the operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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Use the ferror() and feof() functions to distinguish between a read error and an 


end-of-file. 


When using fread () for record input, set size to 1 and count to the maximum 


expected length of the record, to obtain the number of bytes. If you do not know 
the record length, you should set size to 1 and count to a large value. You can read 


only one record at a time when using record I/O. 
Example that uses fread() 


This example attempts to read NUM_ALPHA characters from the file myfile. If 
there are any errors with either fread() or fopen(), a message is printed. 


#include <stdio.h> 
#define NUM ALPHA 26 


int main(void) 
{ 
FILE * stream; 
int num; /* number of characters read from stream «/ 


/* Do not forget that the '\Q' char occupies one character too! */ 
char buffer[NUM_ALPHA + 1]; 


if (( stream = fopen("mylib/myfile", "r"))!= NULL ) 
{ 
memset (buffer, 0, sizeof(buffer)); 
num = fread( buffer, sizeof( char ), NUM_ALPHA, stream ); 
if ( num) { /* fread success */ 
printf( "Number of characters has been read = %i\n", num ); 
printf( "buffer = %s\n", buffer ); 
fclose( stream ); 


} 
else { /* fread failed */ 
if ( ferror(stream) ) /* possibility 1 */ 
perror( "Error reading myfile" ); 
else if ( feof(stream)) /* possibility 2 */ 
perror( "EOF found" ); 
} 


} 
else 
perror( "Error opening myfile" ); 


} 


Related Information 


free() — Release Storage Blocks 


Format 
#include <stdlib.h> 
void free(void *ptr); 


Language Level: ANSI 
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Thread Safe: YES 
Description 


The free() function frees a block of storage. The ptr argument points to a block 
that is previously reserved with a call to the calloc(), malloc(), realloc(), 
_C_TS_calloc(), C_TS_malloc(), C_TS_realloc(), or _C_TS_malloc64() functions. 
The number of bytes freed is the number of bytes specified when you reserved (or 
reallocated, in the case of the realloc() function) the block of storage. If ptr is 
NULL, free() simply returns. 


Note: Attempting to free a block of storage not allocated with calloc(), malloc(), 
or realloc() (or previously freed storage) can affect the subsequent 
reserving of storage and lead to undefined results. Storage that is allocated 
with the ILE bindable API CEEGTST can be freed with free(). 


To use Teraspace storage instead of heap storage without changing the C source 
code, specify the TERASPACE(*YES *TSIFC) parameter on the CRTCMOD compiler 
command. This maps the free() library function to _C_TS_free(), its Teraspace 
storage counterpart. 


Return Value 
There is no return value. 
Example that uses free() 


This example uses the calloc() function to allocate storage for x array elements, 
and then calls the free() function to free them. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 


{ 


long * array; /* start of the array */ 
long * index; /* index variable */ 
int fits /* index variable */ 
int num; /* number of entries of the array */ 


printf( "Enter the size of the array\n" ); 
scanf( "%i", &num ); 


/* allocate num entries */ 
if ( (index = array = calloc( num, sizeof( long ))) != NULL ) 


{ 


for ( i = 0; i < num; ++i ) /* put values in array */ 

*indext+t+ = 7; /* using pointer notation */ 

free( array ); /* deallocates array */ 
else 


{ /* Out of storage */ 
perror( "Error: out of storage" ); 
abort(); 
} 
} 


Related Information 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


freopen() — Redirect Open Files 


Format 


#include <stdio.h> 
FILE *freopen(const char «filename, const char *mode, FILE *stream); 


Language Level: ANSI 
Description 


The freopen() function closes the file that is currently associated with stream and 
reassigns stream to the file that is specified by filename. The freopen() function 
opens the new file associated with stream with the given mode, which is a character 
string specifying the type of access requested for the file. You can also use the 
freopen() function to redirect the standard stream files stdin, stdout, and stderr 
to files that you specify. 


For database files, if filename is an empty string, the freopen() function closes and 
reopens the stream to the new open mode, rather than reassigning it to a new file 
or device. You can use the freopen() function with no file name specified to 
change the mode of a standard stream from text to binary without redirecting the 
stream, for example: 


fp = freopen("", "rb", stdin); 
You can use the same method to change the mode from binary back to text. 


You cannot use the freopen() function with filename as an empty string in modules 
created with SYSIFCOPT(*IFSIO). 


You can use the same method to change the mode from binary back to text. 
Return Value 


The freopen() function returns a pointer to the newly opened stream. If an error 
occurs, the freopen() function closes the original file and returns a NULL pointer 
value. 


The value of errno may be set to: 
Value Meaning 


EBADF 
The file pointer or descriptor is not valid. 


EBADMODE 
The file mode that is specified is not valid. 


EBADNAME 
The file name that is specified is not valid. 


ENOENT 
No file or library. 


ENOTOPEN 
The file is not open. 
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EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Example that uses freopen() 


This example closes the stream1 data stream and reassigns its stream pointer. 
stream1 and stream2 will have the same value, but they will not necessarily have 
the same value as stream. 


#include <stdio.h> 
#define MAX_LEN 100 


int main(void) 

{ 
FILE xstream, «streaml, xstream2; 
char line[MAX_LEN], *result; 
int is; 


stream = fopen("mylib/myfile","r"); 
if ((result = fgets(line,MAX_LEN,stream)) != NULL) 
printf("The string is %s\n", result); 


/* Change all spaces in the line to '*'. */ 
for (i=0; i<=sizeof(line); i++) 
if (line[i] == ' ') 
line[i] = '*'; 


streaml = stream; 

stream2 = freopen("", "wt", streaml); 
fputs( line, stream2 ); 

fclose( stream2) ; 


} 


Related Information 


frexp() — Separate Floating-Point Value 
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Format 


#include <math.h> 
double frexp(double x, int *expptr); 


Language Level: ANSI 

Description 

The frexp() function breaks down the floating-point value x into a term m for the 
mantissa and another term n for the exponent. It is done such that x=m*2 ", and 
the absolute value of m is greater than or equal to 0.5 and less than 1.0 or equal to 
0. The frexp() function stores the integer exponent n at the location to which 


expptr points. 


Return Value 
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The frexp() function returns the mantissa term m. If x is 0, frexp() returns 0 for 
both the mantissa and exponent. The mantissa has the same sign as the argument 
x. The result of the frexp() function cannot have a range error. 


Example that uses frexp() 


This example separates the floating-point value of x, 16.4, into its mantissa 0.5125, 
and its exponent 5. It stores the mantissa in y and the exponent in n. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 


double x, m; 


int n; 
x = 16.4; 
m = frexp(x, n)3 


printf("The mantissa is %1f and the exponent is %d\n", m, n); 


[KEKKRKERKKKERKERERERE Output should be similar tO: ****xkkKKKKEKKKK 


The mantissa is 0.512500 and the exponent is 5 
x/ 


Related Information 


fscanf() — Read Formatted Data 


Format 
#include <stdio.h> 


int fscanf (FILE *stream, const char *format-string, argument-list); 

Language Level: ANSI 

Thread Safe: YES 

Description 

The fscanf() function reads data from the current position of the specified stream 
into the locations that are given by the entries in argument-list, if any. Each entry in 
argument-list must be a pointer to a variable with a type that corresponds to a type 


specifier in format-string. 


The format-string controls the interpretation of the input fields and has the same 
form and function as the format-string argument for the scanf() function. 


Return Value 
The fscanf() function returns the number of fields that it successfully converted 


and assigned. The return value does not include fields that the fscanf() function 
read but did not assign. 
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The return value is EOF if an input failure occurs before any conversion, or the 
number of input items assigned if successful. 


Example that uses fscanf() 


This example opens the file myfile for reading and then scans this file for a string, a 
long integer value, a character, and a floating-point value. 


#include <stdio.h> 
#define MAX_LEN 80 


int main(void) 
{ 
FILE «stream; 
long 13 
float fp; 
char s[MAX_LEN + 1]; 
char c; 


stream = fopen("mylib/myfile", "r"); 
/* Put in various data. */ 


fscanf(stream, "%s", &s [0]); 
fscanf(stream, "%ld", &1); 
fscanf(stream, "%c", &c); 
fscanf(stream, "%f", &fp); 


printf("string = %s\n", s); 
printf("long double = %ld\n", 1); 
printf("char = %c\n", c); 
printf("float = %f\n", fp); 

} 


[KekKKKKKKKKKKKK Tf MYFITE CONTAINS KRKKKKAKKKAKKKAKKKKKKKEK 


KKKKKKKKEKEKKEKE abcdefghijkImnopqrstuvwxyz 343.2 KRKKKKKKKKK 
FEO OO Ore expected OUTPUT 1S: RoR k dm bk kiki 


string = abcdefghijkIlmnopqrstuvwxyz 
long double = 343 

char =. 

float = 2.000000 

*/ 


Related Information 


| fseek() — fseeko() — Reposition File Position 


Format 


#include <stdio.h> 
int fseek(FILE «stream, long int offset, int origin); 
int fseeko(FILE *stream, off_t offset, int origin); 
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Language Level: ANSI 
Description 


The fseek() and fseeko() functions change the current file position that is 
associated with stream to a new location within the file. The next operation on 
stream takes place at the new location. On a stream open for update, the next 
operation can be either a reading or a writing operation. 


The fseeko() function is identical to fseek() except that the offset argument is of 
type off_t_. 


The origin must be one of the following constants that are defined in <stdio.h>: 
Origin Definition 
SEEK_SET 

Beginning of file 


SEEK_CUR 
Current position of file pointer 


SEEK_END 
End of file 


For a binary stream, you can also change the position beyond the end of the file. 
An attempt to position before the beginning of the file causes an error. If 
successful, the fseek() or fseeko() function clears the end-of-file indicator, even 
when origin is SEEK_END, and undoes the effect of any preceding the ungetc() 
function on the same stream. 


Note: 


For streams opened in text mode, the fseek() and fseeko() functions have 
limited use because some system translations (such as those between 
carriage-return-line-feed and new line) can produce unexpected results. The 
only fseek() and fseeko() operations that can be relied upon to work on 
streams opened in text mode are seeking with an offset of zero relative to 
any of the origin values, or seeking from the beginning of the file with an 
offset value returned from a call to the ftell()or ftello() functions. Calls 
to the ftel1() and ftello() functions are subject to their restrictions. 


Return Value 


The fseek() or fseeko function returns 0 if it successfully moves the pointer. A 
nonzero return value indicates an error. On devices that cannot seek, such as 
terminals and printers, the return value is nonzero. 


The value of errno may be set to: 


Value Meaning 


EBADF 
The file pointer or descriptor is invalid. 


EBADSEEK 
Bad offset for a seek operation. 


ENODEV 
Operation was attempted on a wrong device. 
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ENOTOPEN 
The file is not open. 


ERECIO 
The file is open for record I/O. 


ESTDERR 
stderr cannot be opened. 


ESTDIN 
stdin cannot be opened. 


ESTDOUT 
stdout cannot be opened. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


The fseek() and fseeko() functions are not supported for files that are opened 
with type=record. 


Example that uses fseek() 


This example opens a file myfile for reading. After performing input 
operations,fseek() moves the file pointer to the beginning of the file. 


#include <stdio.h> 
#define MAX_LEN 10 


int main(void) 


FILE «stream; 

char buffer[MAX_LEN + 1]; 
int result; 

int i; 

char ch; 


stream = fopen("mylib/myfile", "r"); 
for (i = 0; (i < (sizeof(buffer)-1) && 
((ch = fgetc(stream)) != EOF) && (ch != '\n')); i++) 
buffer[i] = ch; 


result = fseek(stream, OL, SEEK_SET); /* moves the pointer to the */ 
/* beginning of the file */ 
if (result == 0) 
printf("Pointer successfully moved to the beginning of the file.\n"); 
else 
printf("Failed moving pointer to the beginning of the file.\n"); 
} 


Related Information 
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fsetpos() — Set File Position 


Format 


#include <stdio.h> 
int fsetpos(FILE *stream, const fpos_t *pos); 


Language Level: ANSI 
Description 


The fsetpos() function moves any file position that is associated with stream to a 
new location within the file according to the value pointed to by pos. The value of 
pos was obtained by a previous call to the figetpos i library function. 


If successful, fsetpos() clears the end-of-file indicator, and undoes the effect of any 
previous ungetc() function on the same stream. 


After the fsetpos() call, the next operation on a stream in update mode may be 
input or output. 


Return Value 


If fsetpos() successfully changes the current position of the file, it returns 0. A 
nonzero return value indicates an error. 


The value of errno may be set to: 
Value Meaning 


EBADF 
The file pointer or descriptor is invalid.. 


EBADPOS 
The position that is specified is not valid. 


EINVAL 
The value specified for the argument is not correct. You may receive this 
ermo when you compile your program with *IFSIO, and you are working 
with a file in the QSYS file system. For example, 
"/qsys.lib/qtemp.1lib/myfile.file/mymem.mbr" 


ENODEV 

Operation was attempted on a wrong device. 
ENOPOS 

No record at the specified position. 
ERECIO 

The file is open for record I/O. 
ESTDERR 

stderr cannot be opened. 
ESTDIN 

stdin cannot be opened. 
ESTDOUT 

stdout cannot be opened. 
EIOERROR 


A non-recoverable I/O error occurred. 
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EIORECERR 
A recoverable I/O error occurred. 


The fsetpos() function cannot be used for files that are opened with type=record. 
Also, the fsetpos() function can only support setting the position to the beginning 
of the file if: 


* your program is compiled with *IFSIO, and 
* you are working on a file in the QSYS file system. 


Example that uses fsetpos() 


This example opens a file mylib/myfile for reading. After performing input 
operations, fsetpos() moves the file pointer to the beginning of the file and 
rereads the first byte. 


#include <stdio.h> 
FILE «stream; 


int main(void) 
{ 
int retcode; 
fpos_t pos; 
char ptr[20]; | /* existing file 'mylib/myfile' has 20 byte records */ 
int is; 


/* Open file, get position of file pointer, and read first record */ 


stream = fopen("mylib/myfile", "rb"); 

fgetpos (stream, Point-of-Sale); 

if (!fread(ptr,sizeof (ptr) ,1,stream) ) 
perror("fread error"); 

else printf("Ist record: %s\n", ptr); 


/* Perform another read operation on the second record */ 
/* - the value of 'pos' changes */ 
if (!fread(ptr,sizeof(ptr),1,stream) ) 

perror("fread error"); 
else printf("2nd record: %s\n", ptr); 


/* Re-set pointer to start of file and re-read first record */ 
fsetpos (stream, Point-of-Sale) ; 
if (!fread(ptr,sizeof(ptr),1,stream) ) 
perror("fread error"); 
else printf("lst record again: %s\n", ptr); 


fclose(stream) ; 


} 


Related Information 


| ftell() — ftello() — Get Current Position 


| Format 
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#include <stdio.h> 
long int ftell(FILE *stream) ; 
off_t ftello(FILE *stream) ; 


Language Level: ANSI 
Description 


The ftel1() and ftello() functions find the current position of the file associated 
with stream. Por a fixed-length binary file, the value that is returned is an offset 
relative to the beginning of the stream. 


For file in the QSYS library system, the ftel1() and ftello() functions return a 
relative value for fixed-format binary files and an encoded value for other file 
types. This encoded value must be used in calls to the fseek() and 
fseeko()functions to positions other than the beginning of the file. The ftel1() 
and ftello() functions will fail if the file is not a database file or Integrated File 
System file. 


Note: The ftello() function is available only when SYSIFCOPT(*IFSIO) is 
specified on the compilation command. 


Return Value 
The ftel1() and ftello() functions return the current file position. On error, 
ftell() and ftello() return -1, cast to long and off_t respectively, and set 


errno to a nonzero value. 


The value of errno may be set to: 


Value Meaning 


ENODEV 
Operation was attempted on a wrong device. 
ENOTOPEN 
The file is not open. 
ENUMMBRS 
The file is open for multi-member processing. 
ENUMRECS 
Too many records. 
ERECIO 
The file is open for record I/O. 
ESTDERR 
stderr cannot be opened. 
ESTDIN 
stdin cannot be opened. 
ESTDOUT 
stdout cannot be opened. 
EIOERROR 
A non-recoverable I/O error occurred. 
EIORECERR 


A recoverable I/O error occurred. 
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The ftel1() and ftello() functions are not supported for files that are opened 
with type=record. 


Example that uses ftel1() 


This example opens the file mylib/myfile for reading. It reads enough characters to 
fill half of the buffer and prints out the position in the stream and the buffer. 


#include <stdio.h> 


#define NUM ALPHA 26 
#define NUM CHAR 6 


int main(void) 

{ 
FILE * stream; 
int i; 
char ch; 


char buffer[NUM_ALPHA] ; 
long position; 


if (( stream = fopen("mylib/myfile", "r")) != NULL ) 
{ 


/* read into buffer */ 
for ( i = 0; ( i < NUM_ALPHA/2 ) && ((buffer[i] = fgetc(stream)) != EOF ); ++i ) 
if (i==NUM_CHAR-1) /* We want to be able to position the */ 
/* file pointer to the character in 
* 
/ 


/* position NUM CHAR 


*/ 
position = ftell(stream) ; 


buffer[i] = '\O'; 


Related Information 


fwide() — Determine Stream Orientation 
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Format 


#include <stdio.h> 
#include <wchar.h> 
int fwide(FILE «stream, int mode); 


Language Level: ANSI 

Description 

The fwide() function determines the orientation of the stream pointed to by stream. 
If mode is greater than 0, the fwide() function first attempts to make the stream 


wide oriented. If mode is less than 0, the fwide() function first attempts to make 
the stream byte oriented. 
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Note: If the orientation of the stream has already been determined, the fwide() 
function does not change it. 


Otherwise, mode is 0, and the fwide() function does not alter the orientation of the 
stream. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 

Return Value 

If, after the call, the stream has wide orientation, the fwide() function returns a 

value greater than 0. If the stream has byte orientation, it returns a value less than 


0. If the stream has no orientation, it returns 0. 


Example that uses fwide() 
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#include <stdio.h> 
#include <math.h> 
#include <wchar.h> 


void check_orientation(FILE *stream) 


{ 
int rc; 
rc = fwide(stream,0); /* check the orientation */ 
if (re<0) { 
printf("Stream has byte orientation. \n"); 
} else if (rc>0) { 
printf("Stream has wide orientation.\n"); 
} else { 
printf("Stream has no orientation.\n"); 
} 
returns 
} 
int main(void) 
{ 
FILE «stream; 
/* Demonstrate that fwide can be used to set the orientation, 
but cannot change it once it has been set. */ 
stream = fopen("test.dat","w"); 
printf("After opening the file: "); 
check_orientation(stream) ; 
fwide(stream, -1); /* Make the stream byte oriented «/ 
printf("After fwide(stream, -1): "); 
check_orientation(stream) ; 
fwide(stream, 1); /* Try to make the stream wide oriented */ 
printf("After fwide(stream, 1): "); 
check_orientation(stream) ; 
fclose(stream) ; 
printf("Close the stream\n"); 
/* Check that a wide character output operation sets the orientation 
as expected. */ 
stream = fopen("test.dat","w"); 
printf("After opening the file: "); 
check_orientation(stream) ; 
fwprintf(stream, L"pi = %.5f\n", 4* atan(1.0)); 
printf("After fwprintf( ): "); 
check_orientation(stream) ; 
fclose(stream) ; 
return 0; 
[RRR R KKK EKER KKK AKER A KEK KKK K KAKA KKK KEKE AKIRA KEE AKER ARE RK 
The output should be similar to : 
After opening the file: Stream has no orientation. 
After fwide(stream, -1): Stream has byte orientation. 
After fwide(stream, 1): Stream has byte orientation. 
Close the stream 
After opening the file: Stream has no orientation. 
After fwprintf( ): Stream has wide orientation. 
KKK AK KKK KK KKK KKK KKK KK KKK KKK KKK A KKK KKK KKK KKK KKK KKK EA KKK KE | 
} 


Related Information 


122 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


fwprintf() — Format Data as Wide Characters and Write to a Stream 


Format 


#include <stdio.h> 
#include <wchar.h> 
int fwprintf(FILE *stream, const wchar_t *format, argument-list); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fwprintf() function writes output to the stream pointed to by stream, under 
control of the wide string pointed to by format. The format string specifies how 
subsequent arguments are converted for output. 


The fwprintf() function converts each entry in argument-list according to the 
corresponding wide-character format specifier in format. 


If insufficient arguments exist for the format, the behavior is undefined. If the 
format is exhausted while arguments remain, the fwprintf() function evaluates, as 
usual, the excess arguments, but otherwise ignores them. The fwprintf () function 
returns when it encounters the end of the format string. 


The format comprises zero or more directives: ordinary wide characters (not %) 
and conversion specifications. Conversion specifications are processed as if they 
were replaced in the format string by wide-character strings. The wide-character 
strings are the result of fetching zero or more subsequent arguments and then 
converting them, if applicable, according to the corresponding conversion specifier. 
The fwprintf() function then writes the expanded wide-character format string to 
the output stream. 


The format for the fwprintf() function has the same form and function as the 
format string for printf(), with the following exceptions: 


* %oc (without an | prefix) converts an integer argument to wchar_t, as if by calling 
the btowc() function. 


* %s (without an | prefix) converts an array of multibyte characters to an array of 
wchar_t, as if by calling the mbrtowc() function. The array is written up to, but 
not including, the terminating null character, unless the precision specifies a 
shorter output. 

* %ls and %S write an array of wchar_t. The array is written up to, but not 
including, the ending null character, unless the precision specifies a shorter 
output. 


If a conversion specification is invalid, the behavior is undefined. 

If any argument is, or points to, an union or an aggregate (except for an array of 
char type using %s conversion, an array of wchar_t type using %ls conversion, or a 
pointer using Yop conversion), the behavior is undefined. 

In no case does a nonexistent, or small field width, cause truncation of a field; if 


the conversion result is wider than the field width, the field is expanded to contain 
the conversion result. 
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Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The fwprintf() function returns the number of wide characters transmitted. If an 
output error occurred, it returns a negative value. 


Example that uses fwprintf () 


Note: When writing wide characters, the file should be opened in binary mode, or 
the file must be opened with the o_ccsid or codepage parameters. This 
ensures that no conversions occur on your wide characters. Since there are 
no valid double-byte job CCSIDS on the iSeries, any conversion would be 
invalid. 
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#include <stdio.h> 
#include <wchar.h> 
#include <locale.h> 


int count [10] = {1, 5, 8, 3, 0, 3, 5, 6, 8, 10}; 


int main(void) 
{ 
int: 1s38 


FILE «stream; 


/* Open the stream for writing */ 


if (NULL == (stream = fopen("/QSYS.LIB/LIB.LIB/WCHAR.FILE/WCHAR.MBR", "wb"))) 


perror("fopen error"); 


for (i=0; i < sizeof(count) / sizeof(count[0]); i++) 


{ 
for (j = 0; j < count[i]; j++) 
fwprintf(stream, L"*"); 
/* Print asterisk */ 
fwprintf(stream, L"\n"); 
/* Move to the next line x/ 
} 
fclose (stream) ; 
} 
/* 


The member WCHAR of file WCHAR will contain: 


KKEKK 
KKKKKKKEK 


KKK 


KKK 


KKKKK 
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Unicode example that uses fwprintf() 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
/* This program is compile LOCALETYPE(*LOCALEUCS2) and 
/* SYSIFCOPT(*IFSIO) 
int main(void) 
{ 
FILE *stream; 
wchar_t we = 0x0058; /* UNICODE X */ 
char cl = 'c'; 
char *sl = "123"; 
wchar_t ws[4]; 
setlocale(LC_ALL, 
"/QSYS.LIB/EN_US.LOCALE"); /* a CCSID 37 locale */ 
ws [0] 0x0041; /* UNICODE A */ 
ws[1] = (wchar_t)0x0042; /* UNICODE B- x/ 
ws[2] = (wchar_t)0x0043; /* UNICODE C */ 
ws[3] = (wchar_t)0x0000; 


stream = fopen("myfile.dat", "wb+"); 


/* 1c and 1s take wide char as input and just copies th 
/* to the file. So the file would look like this 

/* after the below fwprintf statement: 

/* 0058002000200020004100420043 

/* 0020 is UNICODE blank 


fwprintf(stream, L"%lc %1s",wc,ws); 

/* c and s take multibyte as input and produce UNICODE 
/* In this case cl and sl are CCSID 37 characters based 
/* on the setlocale above. So the characters are 

/* converted from CCSID 37 to UNICODE and will look 

/* like this in hex after the following fwprintf 

/* statment: 0063002000200020003100320033 

/* 0063 is a UNICODE c 0031 is a UNICODE 1 and so on 


fwprintf(stream, L"%c %s",cl,s1); 

/* Now lets try width and precision. 61s means write 
/* 6 wide characters so we will pad with 3 UNICODE 

/* blanks and %.2s means write no more then 2 wide 

/* characters. So we get an output that looks like 
/* this: 00200020002000410042004300310032 


fwprintf(stream, L"%61s%.2s",ws,s1); 


Related Information 
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en 


*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 


*/ 
*/ 


fwrite() — Write Items 


Format 


#include <stdio.h> 
size_t fwrite(const void «buffer, size_t size, size_t count, 
FILE *stream) ; 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fwrite() function writes up to count items, each of size bytes in length, from 
buffer to the output stream. 


Return Value 


The fwrite() function returns the number of full items successfully written, which 
can be fewer than count if an error occurs. 


When using fwri te() for record output, set size to 1 and count to the length of the 
record to obtain the number of bytes written. You can only write one record at a 
time when using record I/O. 


The value of errno may be set to: 
Value Meaning 


ENOTWRITE 
The file is not open for write operations. 


EPAD Padding occurred on a write operation. 


EPUTANDGET 
An illegal write operation occurred after a read operation. 


ESTDERR 
stderr cannot be opened. 


ESTDIN 
stdin cannot be opened. 


ESTDOUT 
stdout cannot be opened. 


ETRUNC 
Truncation occurred on I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Example that uses fwrite() 
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This example writes NUM long integers to a stream in binary format. 


#include <stdio.h> 
#define NUM 100 


int main(void) 
{ 
FILE «stream; 
long list[NUM] ; 
int numwritten; 
int i; 
stream = fopen("MYLIB/MYFILE", "wtb"); 
/* assign values to list[] */ 
for (i=0; i<=NUM; i++) 
list[i]=i; 


numwritten = fwrite(list, sizeof(long), NUM, stream); 
printf("Number of items successfully written = %d\n", numwritten); 


} 


Related Information 


fwscanf() — Read Data from Stream Using Wide Character 
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Format 


#include <stdio.h> 
#include <wchar.h> 
int fwscanf(FILE «stream, const wchar_t «format, argument-list); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The fwscanf() function reads input from the stream pointed to by stream, under 
control of the wide string pointed to by format. The format string specifies the 
admissible input sequences and how they are to be converted for assignment. To 
receive the converted input, the fwscanf() function uses subsequent arguments as 
pointers to the objects. 


Each argument in argument-list must point to a variable with a type that 
corresponds to a type specifier in format. 


If insufficient arguments exist for the format, the behavior is undefined. If the 
format is exhausted while arguments remain, the fwscanf() function evaluates the 
excess arguments, but otherwise ignores them. 


The format consists of zero or more directives: one or more white-space wide 
characters; an ordinary wide character (neither % nor a white-space wide 
character); or a conversion specification. Each conversion specification is 
introduced by a %. 
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The format has the same form and function as the format string for the 

scanf()function, with the following exceptions: 

* %oc (with no | prefix) converts one or more wchar_t characters (depending on 
precision) to multibyte characters, as if by calling wcrtomb(). 


%lc and %C convert one or more wchar_t characters (depending on precision) to 
an array of wchar_t. 


* %s (with no | prefix) converts a sequence of non-white-space wchar_t characters 
to multibyte characters, as if by calling the wcrtomb() function. The array 
includes the ending null character. 


* %ls and %S copy an array of wchar_t, including the ending null wide character, 
to an array of wchar_t. 


If the data is from stdin, and stdin has not been overridden, the data is assumed 
to be in the CCSID of the job. The data is converted as required by the format 
specifications. If the file that is being read is not opened with file mode rb, then 
invalid conversion will occur as there are no valid wide job CCSIDs. 


If a conversion specification is invalid, the behavior is undefined. If the fwscanf () 
function encounters end-of-file during input, conversion is ended. If end-of-file 
occurs before the fwscanf() function reads any characters matching the current 
directive (other than leading white space, where permitted), execution of the 
current directive ends with an input failure. Otherwise, unless execution of the 
current directive terminates with a matching failure, execution of the following 
directive (other than %n, if any) ends with an input failure. 


The fwscanf() function leaves trailing white space (including new-line wide 

characters) unread, unless matched by a directive. You cannot determine the 

success of literal matches and suppressed assignments other than through the %n 

directive. 

Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The fwscanf() function returns the number of input items assigned, which can be 
fewer than provided for, in the event of an early matching failure. 


If an input failure occurs before any conversion, the fwscanf () function returns 
EOF 


Example that uses fwscanf() 


This example opens the file myfile.dat for input, and then scans this file for a 
string, a long integer value, a character, and a float.. 
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#include <stdio.h> 
#include <wchar.h> 


#define MAX_LEN 80 
int main(void) 


FILE *stream; 

long 13 

float fp; 

char s[MAX_LEN+1]; 
char c; 


stream = fopen("myfile.dat", "r"); 
/* Read data from file. */ 


fwscanf(stream, L"%s", &s[0]); 
fwscanf(stream, L"%ld", &1); 
fwscanf(stream, L"%c", &c); 
fwscanf(stream, L"%f", &fp); 


printf("string = %s\n", s); 
printf("long integer = %ld\n", 1); 
printf("char = %c\n", c); 
printf("float = %f\n", fp); 

return 0; 


[BRK R KKK KK ERK KER AKER A KKK KEI KKK IK KEK KKK KER KK 


If myfile.dat contains: 
abcdefghijkIlmnopqrstuvwxyz 343.2. 


The output should be: 


string = abcdefghijkIlmnopqrstuvwxyz 
long integer = 343 

char =. 

float = 2.000000 


KKK KKK KKK KK KK KKK RK KKK KKK KKK KKK KKK K KEK KERR KKK | 


} 


UNICODE example that uses fwscanf () 
This example reads a UNICODE string from unicode.dat and prints it to the 


screen. The example is compiled with LOCALETYPE(*LOCALEUCS2) 
SYSIFCOPT(*IFSIO): 
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#include <stdio.h> 

#include  <wchar.h> 

#include <locale.h> 

void main(void) 

{ 

FILE «stream; 

wehar_t buffer[20]; 
setlocale(LC_UCS2_ALL,""); 
stream=fopen("unicode.dat","rb"); 


fwscanf(stream,L"%1s", buffer); 
wprintf(L"The string read was :%1s\n",buffer) ; 


fclose(stream) ; 


} 


/* If the input in unicode.dat is : 

ABC 

and ABC is in unicode which in hex would be 0x0041, 0x0042, 0x0043 
then the output will be similiar to: 

The string read was :ABC 

* 

/ 


Related Information 


gamma() — Gamma Function 
Format 
#include <math.h> 
double gamma(double x); 
Language Level: ILE C Extension 


Description 


The gamma() function computes the natural logarithm of the absolute value of G(x) 
(In(| G(x) !)), where 


G(x) a etx t™ lat 
0 


The argument x must be a positive real value. 

Return Value 

The gamma() function returns the value of In(|G(x)|). If x is a negative value, errno 
is set to EDOM. If the result causes an overflow, gamma() returns HUGE_VAL and 
sets errno to ERANGE. 
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Example that uses gamma() 
This example uses gamma() to calculate In(|G(x)!), where x = 42. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
double x=42, g_at_x; 
g_at_x = exp(gamma(x)); /* g_at_x = 3.345253e+49 x/ 


printf ("The value of G(%4.21f) is %7.2e\n", x, g_at_x); 
} 


[EK RKKER EKER KKERKKERKEKREK Output should be similar to: ********** 


The value of G(42.00) is 3.35e+49 
*/ 


Related Information 


_gcvt - Convert Floating-Point to String 


Format 


#include <stdlib.h> 
char *_gcvt(double value, int ndec, char «buffer); 


Note: The _gcvt function is supported only for C++, not for C. 

Language Level: Extension 

Description 

_gcvt() converts a floating-point value to a character string pointed to by buffer. 
The buffer should be large enough to hold the converted value and a null character 
(\0) that _gcvt() automatically adds to the end of the string. There is no provision 
for overflow. 

_gcvt() attempts to produce ndec significant digits in FORTRAN F format. Failing 
that, it produces ndec significant digits in FORTRAN E format. Trailing zeros might 
be suppressed in the conversion if they are insignificant. 


A FORTRAN F number has the following format: 


>> digit - | 
+ digit digit 


>< 


A FORTRAN E number has the following format: 
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>< 


+: | sigit_| 


>> : digit—.—digit—E digit 
= 


_gcvt also converts NaN and infinity values to the strings NAN and INFINITY, 
respectively. 


Return Value 


_gcvt() returns a pointer to the string of digits. If it cannot allocate memory to 
perform the conversion, _gcvt() returns an empty string and sets errno to 
ENOMEM. 


Example that uses _gcvt() 


This example converts the value -3.1415e3 to a character string and places it in the 
character array bufferl. 
#include <stdio.h> 
#include <stdlib.h> 
int main(void) 
{ 
char buffer1[10]; 
_gcvt(-3.1415e3, 7, bufferl); 
printf("The first result is %s \n", bufferl); 
return 0; 


} 


The output should be: 
The first result is -3141.5 


Related Information: 
* Infinity and NaN Support 
¢ <stdlib.h> 


getc() — getchar() — Read a Character 


Format 


#include <stdio.h> 
int getc(FILE *stream) ; 
int getchar(void); 


Language Level: ANSI 

Thread Safe: NO. #undef getc or #undef getchar allows the getc or getchar 
function to be called instead of the macro version of these functions. The functions 
are thread safe. 

Description 

The getc() function reads a single character from the current stream position and 


advances the stream position to the next character. The getchar() function is 
identical to getc(stdin). 
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The difference between the getc() and fgetc() functions is that getc() can be 
implemented so that its arguments can be evaluated multiple times. Therefore, the 
stream argument to getc() should not be an expression with side effects. 


Return Value 


The getc() and getchar() functions return the character read. A return value of 
EOF indicates an error or end-of-file condition. Use ferror() or feof() to 
determine whether an error or an end-of-file condition occurred. 


The value of errno may be set to: 
Value Meaning 


EBADF 
The file pointer or descriptor is not valid. 


EGETANDPUT 
An illegal read operation occurred after a write operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


The getc() and getchar() functions are not supported in record mode. 
Example that uses getc() 


This example gets a line of input from the stdin stream. You can also use 
getc(stdin) instead of getchar() in the for statement to get a line of input from 
stdin. 


#include <stdio.h> 
#define LINE 80 


int main(void) 

{ 
char buffer[LINE+1]; 
int i; 
int ch; 


printf( "Please enter string\n" ); 


/* Keep reading until either: 
1. the length of LINE is exceeded or 
2. the input character is EOF or 
3. the input character is a new-line character 


x/ 
for (i = 0; (i < LINE ) && (( ch = getchar()) != EOF) && 
(ch !='\n' ); ++i ) 
buffer[i] = ch; 
buffer[i] = '\O0'; /* a string should always end with '\Q' ! «/ 


printf( "The string is %s\n", buffer ); 
} 


Related Information 
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getenv() — Search for Environment Variables 


Format 


#include <stdlib.h> 
char *getenv(const char *varname) ; 


Language Level: ANSI 
Description 


The getenv() function searches the list of environment variables for an entry 
corresponding to varname. 


Return Value 


The getenv() function returns a pointer to the string containing the value for the 
specified varname in the current environment. If getenv() cannot find the 
environment string, NULL is returned, and errno is set to indicate the error. 


Example that uses getenv() 


#include <stdlib.h> 
#include <stdio.h> 


/* Where the environment variable 'PATH' is set to a value. */ 
int main(void) 
char *pathvar; 

pathvar = getenv("PATH"); 

printf ("pathvar=%s",pathvar) ; 


} 


Related Information 


* Environment Variable - See the [API topic 


_GetExcData() — Get Exception Data 


Format 
#include <signal.h> 


void _GetExcData(_INTRPT_Hndlr_Parms_T *parms) ; 
Language Level: ILE C Extension 


Description 


Chapter 2. Library Functions 135 


136 


The _GetExcData() function returns information about the current exception from 
within a C signal handler. The caller of the _GetExcData() function must allocate 
enough storage for a structure of type .INTRPT_Hndlr_Parms_T. If the 
_GetExcData() function is called from outside a signal handler, the storage pointed 
to by parms is not updated. 


This function is not available when SYSIFCOPT(*ASYNCSIGNAL) is specified on 
the compilation commands. When SYSIFCOPT(*ASYNCSIGNAL) is specified, a 
signal handler established with the ILE C signal() function has no way to access 
any exception information that may have caused the signal handler to be invoked. 
An extended signal handler established with the OS/ 400® sigaction() function, 
however, does have access to this exception information. The extended signal 
handler has the following function prototype: 


void func( int signo, siginfo_t «info, void «context ) 


The exception information is appended to the siginfo_t structure, which is then 
passed as the second parameter to the extended signal handler. 


The siginfo_t structure is defined in signal.h. The exception-related data follows 
the si_sigdata field in the siginfo_tstructure. You can address it from the se data 
field of the sigdata_t structure. 


The format of the exception data appended to the siginfo_t structure is defined 
by the LINTRPT_Hndlr_Parms_T structure in except.h. 


Return Value 
There is no return value. 
Example that uses _GetExcData() 


This example shows how exceptions from MI library functions can be monitored 
and handled using a signal handling function. The signal handler 
my_signal_handler is registered before the rslvsp() function signals a 0x2201 
exception. When a SIGSEGV signal is raised, the signal handler is called. If an 
0x2201 exception occurred, the signal handler calls the QUSRCRTS API to create a 
space. 
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#include <signal.h> 

#include <QSYSINC/MIH/RSLVSP> 
#include <QSYSINC/H/QUSCRTUS> 
#include <string.h> 

#define CREATION SIZE 65500 
void my_signal_handler(int sig) { 


_INTRPT_Hnd1lr_Parms_T excp_data; 
int error_code = Q; 


/* Check the message id for exception 0x2201 «/ 
_GetExcData(&excp_data) ; 


if (!memcmp(excp_data.Msg Id, "MCH3401", 7)) 


QUSCRTUS ("MYSPACE  QTEMP ar 
"MYSPACE ", 
CREATION SIZE, 
"\Oo", 
"SALL a 
"MYSPACE example for Programmer's Reference my 
"YES ae 


&error_code) ; 


Related Information 


gets() — Read a Line 


Format 

#include <stdio.h> 

char *gets(char *buffer); 

Language Level: ANSI 

Thread Safe: YES 

Description 

The gets() function reads a line from the standard input stream stdin and stores 
it in buffer. The line consists of all characters up to but not including the first 
new-line character (\n) or EOF. The gets() function then replaces the new-line 
character, if read, with a null character (\0) before returning the line. 

Return Value 

If successful, the gets() function returns its argument. A NULL pointer return 
value indicates an error, or an end-of-file condition with no characters read. Use 
the ferror() function or the feof() function to determine which of these 
conditions occurred. If there is an error, the value that is stored in buffer is 
undefined. If an end-of-file condition occurs, buffer is not changed. 


Example that uses gets () 


This example gets a line of input from stdin. 
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#include <stdio.h> 
#define MAX_LINE 100 


int main(void) 

{ 
char line[MAX_LINE]; 
char *result; 


printf("Please enter a string:\n"); 
if ((result = gets(line)) != NULL) 
printf("The string is: %s\n", line); 
else if (ferror(stdin)) 
perror("Error"); 
} 


Related Information 


getwc() — Read Wide Character from Stream 


138 


Format 


#include <stdio.h> 
#include <wchar.h> 
wint_t getwc(FILE *stream) ; 


Language Level: ANSI 
Thread Safe: YES 
Description 


The getwc() function reads the next multibyte character from stream, converts it to 
a wide character, and advances the associated file position indicator for stream. 


The getwc() function is equivalent to the fgetwc() function except that, if it is 
implemented as a macro, it can evaluate stream more than once. Therefore, the 
argument should never be an expression with side effects. 


The behavior of the getwc() function is affected by the LC_CTYPE category of the 
current locale. If you change the category between subsequent read operations on 
the same stream, undefined results can occur. Using non-wide-character functions 
with the getwc() function on the same stream results in undefined behavior. 


After calling the getwc() function, flush the buffer or reposition the stream pointer 
before calling a write function for the stream, unless EOF has been reached. After a 
write operation on the stream, flush the buffer or reposition the stream pointer 
before calling the getwc() function. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Note: This function is available when SYSIFCOPT(*IFSIO) and 


LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 


on the compilation command. 


Return Value 


The getwc() function returns the next wide character from the input stream, or 
WEOEF. If an error occurs, the getwc() function sets the error indicator. If the 
getwc() function encounters the end-of-file, it sets the EOF indicator. If an 
encoding error occurs during conversion of the multibyte character, the getwc() 


function sets errno to EILSEQ. 


Use the ferror() or feof() functions to determine whether an error or an EOF 


condition occurred. EOF is only reached when an attempt is made to read past the 
last byte of data. Reading up to and including the last byte of data does not turn 
on the EOF indicator. 


Example that uses getwc() 


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 


int main(void) 


{ 


} 


FILE «stream; 
wint_t we; 


if (NULL == (stream = fopen("getwc.dat", "r"))) { 
printf("Unable to open: \"getwc.dat\"\n"); 
exit(1); 

} 


errno = Q; 
while (WEOF != (wc = getwc(stream))) 
printf("we = %lc\n", wc); 


if (EILSEQ == errno) { 
printf("An invalid wide character was encountered. \n"); 
exit(1); 

} 

fclose(stream) ; 

return 0; 


[RK RK REAR KEI AKER KKK AK KKK A KKK KKK IK KKK KK KKK A AKER KK 
Assuming the file getwc.dat contains: 


Hello world! 


The output should be similar to: 


we = H 
we =e 
we = | 
we = | 
=0 


wc 
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Related Information 
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getwchar() — Get Wide Character from stdin 
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Format 


#include <wchar.h> 
wint_t getwchar(void); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The getwchar() function reads the next multibyte character from stdin, converts it 
to a wide character, and advances the associated file position indicator for stdin. A 
call to the getwchar() function is equivalent to a call to getwc(stdin). 


The behavior of the getwchar() function is affected by the LC_CTYPE category of 
the current locale. If you change the category between subsequent read operations 
on the same stream, undefined results can occur. Using non-wide-character 
functions with the getwchar() function on stdin results in undefined behavior. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The getwchar() function returns the next wide character from stdin or WEOFR If 
the getwchar() function encounters EOF, it sets the EOF indicator for the stream 
and returns WEOF. If a read error occurs, the error indicator for the stream is set, 
and the getwchar() function returns WEOF. If an encoding error occurs during the 
conversion of the multibyte character to a wide character, the getwchar() function 
sets errno to EILSEQ and returns WEOF. 


Use the ferror() or feof() functions to determine whether an error or an EOF 
condition occurred. EOF is only reached when an attempt is made to read past the 
last byte of data. Reading up to and including the last byte of data does not turn 
on the EOF indicator. 


Example that uses getwchar() 


This example uses the getwchar() to read wide characters from the keyboard, then 
prints the wide characters. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <errno.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 


int main(void) 
{ 


wint_t we; 


errno = Q; 
while (WEOF != (wc = getwchar())) 
printf("we = %lc\n", wc); 


if (EILSEQ == errno) { 
printf("An invalid wide character was encountered.\n"); 
exit(1); 

} 


return 0; 


[KEK KKK KKK KEIR KKK KKK AK KKK KKK IKKE AK KEIR KAKA KKK KEK KKK KEI 


Assuming you enter: abcde Z (note: “Z is CNTRL-Z) 


The output should be: 


we=a 
we = b 
we =C 
we = d 
we =e 
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} 


Related Information 


gmtime() — Convert Time 
Format 
#include <time.h> 
struct tm *gmtime(const time_t *time); 
Language Level: ANSI 
Thread Safe: NO. Use gmtime_r() instead. 
Description 
The gmtime() function breaks down the time value, in seconds, and stores it in a tm 
structure, defined in <time.h>. The value time is usually obtained by a call to the 


time() function. 


The fields of the tm structure include: 
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tm_sec 
Seconds (0-61) 


tm_min 
Minutes (0-59) 
tm_hour 


Hours (0-23) 


tm_mday 
Day of month (1-31) 


tm_mon 
Month (0-11; January = 0) 


tm_year 
Year (current year minus 1900) 


tm_wday 

Day of week (0-6; Sunday = 0) 
tm_yday 

Day of year (0-365; January 1 = 0) 
tm_isdst 


Zero if Daylight Saving Time is not in effect; positive if Daylight Saving 
Time is in effect; negative if the information is not available. 


Return Value 
The gmtime() function returns a pointer to the resulting tm structure. 


Note: 

* The range (0-61) for tm_sec allows for as many as two leap seconds. 

* The gmtime() and localtime() functions may use a common, statically 
allocated buffer for the conversion. Each call to one of these functions 
may alter the result of the previous call. 

* Calendar time is the number of seconds that have elapsed since EPOCH, 
which is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 

* The time() function uses the QUTCOFFSET system value for calculating 
UTC. The QUTCOFFSET value specifies the difference in hours and 
minutes between UTC, also known as Greenwich mean time, and the 
current system time. You can override the QUTCOFFSET value by 
specifying the TZDIFF and TZNAME category of the current locale. 


Note: This function is locale sensitive. 
Example that uses gmt ime() 
This example uses the gmtime() function to adjust a time_t representation to a 


Coordinated Universal Time character string, and then converts it to a printable 
string using the asctime() function. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <time.h> 


int main(void) 
{ 
time_t ltime; 
time(localtime()); 
printf ("Coordinated Universal Time is %s\n", 
asctime(gmtime(localtime()))); 
} 


[ REKRKEEK KEKE EKER RERERER Output should be similar to: «*********k* 


Coordinated Universal Time is Wed Aug 18 21:01:44 1993 
x/ 


Related Information 


gmtime_r() — Convert Time (Restartable) 


Format 


#include <time.h> 
struct tm *gmtime_r(const time_t *time, struct tm *result); 


Description 
This function is the restartable version of gmtime(). 


The gmtime_r() function breaks down the time value, in seconds, and stores it in a 
tm structure, defined in <time.h>. The value time is usually obtained by a call to 
the time() function. 


The fields of the tm structure include: 


tm_sec 
Seconds (0-61) 


tm_min 
Minutes (0-59) 


tm_hour 
Hours (0-23) 


tm_mday 
Day of month (1-31) 
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tm_mon 
Month (0-11; January = 0) 


tm_year 
Year (current year minus 1900) 


tm_wday 
Day of week (0-6; Sunday = 0) 


tm_yday 
Day of year (0-365; January 1 = 0) 


tm_isdst 
Zero if Daylight Saving Time is not in effect; positive if Daylight Saving 
Time is in effect; negative if the information is not available. 


Return Value 
The gmtime_r() function returns a pointer to the resulting tm structure. 


Note: 
* The range (0-61) for tm_sec allows for as many as two leap seconds. 


* The gmtime() and localtime() functions may use a common, statically 
allocated buffer for the conversion. Each call to one of these functions 
may alter the result of the previous call. The asctime_r(), ctime_r(), 
gmtime_r(), and localtime_r() functions do not use a common, 
statically-allocated buffer to hold the return string. These functions can be 
used in the place of the asctime(), ctime(), gmtime(), and localtime() 
functions if reentrancy is desired. 


* Calendar time is the number of seconds that have elapsed since EPOCH, 
which is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 


* The time() function uses the QUTCOFFSET system value for calculating 
UTC. The QUTCOFFSET value specifies the difference in hours and 
minutes between UTC, also known as Greenwich mean time, and the 
current system time. You can override the QUTCOFFSET value by 
specifying the TZDIFF and TZNAME category of the current locale. 


Example that uses gmt ime_r() 
This example uses the gmtime_r() function to adjust a time_t representation to a 


Coordinated Universal Time character string, and then converts it to a printable 
string using the asctime_r() function. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <time.h> 


int main(void) 

{ 
time_t ltime; 
struct tm mytime; 
char buf[50]; 


time(localtime()); 
printf ("Coordinated Universal Time is %s\n", 
asctime_r(gmtime_r(localtime(), &mytime), buf)); 


} 


[KEK RKKEKKEK ERK RRR KKERERER Output should be similar to: «*********ex* 


Coordinated Universal Time is Wed Aug 18 21:01:44 1993 
x/ 


Related Information 


hypot() — Calculate Hypotenuse 


Format 
#include <math.h> 


double hypot(double sidel, double side2); 

Language Level: ILE C Extension 

Description 

The hypot() function calculates the length of the hypotenuse of a right-angled 


triangle based on the lengths of two sides side1 and side2. A call to the hypot() 
function is equivalent to: 


sqrt(sidel * sidel + side2 * side2); 
Return Value 
The hypot() function returns the length of the hypotenuse. If an overflow results, 
hypot() sets errno to ERANGE and returns the value HUGE_VAL. If an underflow 
results, hypot() sets errno to ERANGE and returns zero. The value of errno may 


also be set to EDOM. 


Example that uses hypot() 
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This example calculates the hypotenuse of a right-angled triangle with sides of 3.0 
and 4.0. 


#include <math.h> 


int main(void) 
{ 


double x, y, Z3 


x = 3.0; 
y = 4.0; 
z = hypot(x,y)s 


printf("The hypotenuse of the triangle with sides %1f and %1f" 
"is %1f\n", x, y, Zz) 


} 


[KEKRKRKEKRKEKEREKER EKER Output should be similar to: ******kk*kKKEKK 


The hypotenuse of the triangle with sides 3.000000 and 4.000000 is 5.000000 
*/ 


Related Information 


isascii() — Test for ASCII Value 
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Format 

#include <ctype.h> 

int isascii(int c); 
Language Level: XPG4 


Description 


The isascii() function tests if an EBCDIC character, in the current locale, is a 
valid 7—-bit US-ASCII character. 


Return Value 


The isascii() function returns nonzero if c is the EBCDIC encoding, in the current 
locale, for a character in the 7—bit US-ASCII character set. Otherwise, it returns 0. 


Example that uses isascii() 


This example tests the integers from 0x7c to 0x82, and prints the corresponding 
ASCII character if the integer is within the ASCII range. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <ctype.h> 


int main(void) 
{ 


int ch; 


for (ch = Ox7c; ch <= 0x82; cht+) { 
printf ("%#04x ", Gh); 
if (isascii(ch)) 
printf("The ASCII character is %c\n", ch); 
else 
printf("Not an ASCII character\n"); 


return 0; 


} 


[BRK KKK RAK ERIK KERR KEI KIEK KKK KEKE IKKE KKK K EK 


The output should be: 


Ox7c The ASCII character is @ 
0x7d The ASCII character is ' 
0x7e The ASCII character is = 
Ox7f The ASCII character is " 
0x80 Not an ASCII character 

0x81 The ASCII character is a 
0x82 The ASCII character is b 
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Related Information 


isalnum() - isxdigit() — Test Integer Value 


Format 


#include <ctype.h> 

int isalnum(int c); 

/* Test for upper- or lowercase letters, or decimal digit */ 
int isalpha(int c); 

/* Test for alphabetic character */ 

int iscntrl(int c); 

/* Test for any control character */ 

int isdigit(int c); 

/* Test for decimal digit */ 

int isgraph(int c); 

/* Test for printable character excluding space */ 
int islower(int c); 

/* Test for lowercase */ 

int isprint(int c); 

/* Test for printable character including space */ 
int ispunct(int c); 

/* Test for any nonalphanumeric printable character */ 
/* excluding space */ 

int isspace(int c); 

/* Test for whitespace character */ 

int isupper(int c); 
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/* Test for uppercase */ 
int isxdigit(int c); 
/* Test for hexadecimal digit */ 


Language Level: ANSI 

Description 

The <ctype.h> functions listed test a character with an integer value. The 
LC_CTYPE category of the active locale determines the results returned from these 
functions. 

Return Value 

These functions return a nonzero value if the integer satisfies the test condition, or 
a zero value if it does not. The integer variable c must be representable as an 
unsigned char. 

Note: EOF is a valid input value. 

Example that uses <ctype.h> functions 

This example analyzes all characters between code 0x0 and code UPPER_LIMIT, 
printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L for 
lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for punctuation, 
PR for printable characters, G for graphics characters, and C for control characters. 


This example prints the code if printable. 


The output of this example is a 256-line table showing the characters from 0 to 255 
that possess the attributes tested. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <ctype.h> 


#define UPPER_LIMIT OxFF 


int main(void) 


{ 

int ch; 

for ( ch = 0; ch <= UPPER LIMIT; ++ch ) 

{ 
printf("%3d ", ch); 
printf ("%#04x ", ch); 
printf("%3s ", isalnum(ch) 
printf("%2s ", isalpha(ch) 
printf("%2s", iscntr1(ch) 
printf("%2s", isdigit(ch) 
printf("%2s", isgraph(ch) 
printf("%2s", islower(ch) 
printf(" %c", isprint(ch) 
printf("%3s", ispunct(ch) 
printf("%2s", isspace(ch) 
printf("%3s",  isprint(ch) 
printf("%2s", isupper(ch) 
printf("%2s", isxdigit(ch) 
putchar('\n'); 

} 

} 


Related Information 


OND DD DD OD DDD OD 


"AN" : 


mau 
en 
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"DR" : 


nye 
nyu 


"py" : 


| isblank() — Test for Blank or Tab Character 


Format 


#include <ctype.h> 
int isblank(int c); 


Note: The isblank() function is supported only for C++, not for C. 


Thread Safe: YES. 


Description 


The isblank() function tests if a character is either the EBCDIC space or EBCDIC 


tab character. 


Return Value 


The isblank() function returns nonzero if c is either the EBCDIC space character 


or the EBCDIC tab character, otherwise it returns 0. 


Example that uses isblank() 


This example tests several characters using isblank(). 
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#include <stdio.h> 
#include <ctype.h> 


int main(void) 


char *buf = "a b\tc"; 
int i; 


for (i = 0; i < 5; i++) { 
if (isblank(buf[i])) 
printf("Character %d is not a blank.\n", i); 
else 
printf("Character %d is a blank\n", i); 
} 
return 0; 


} 


[BRK R KKK KKK KERR KEK KER EKER AK ERA REA 


The output should be 


Character 0 is not a blank. 
Character 1 is a blank. 
Character 2 is not a blank. 
Character 3 is a blank. 
Character 4 is not a blank. 
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Related Information 


iswalnum() to iswxdigit() — Test Wide Integer Value 


Format 


#include <wctype.h> 

int iswalnum(wint_t wc); 
int iswalpha(wint_t wc); 
int iswentr] (wint_t we); 
int iswdigit(wint_t wc); 
int iswgraph(wint_t wc); 
int iswlower(wint_t wc); 
int iswprint(wint_t wc); 
int iswpunct(wint_t wc); 
int iswspace(wint_t wc); 
int iswupper(wint_t wc); 
int iswxdigit(wint_t wc); 


Thread Safe: YES. 
Description 


The functions listed above, which are all declared in <wctype.h>, test a given wide 
integer value. 
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The value of we must be a wide-character code corresponding to a valid character 
in the current locale, or must equal the value of the macro WEOF. If the argument 
has any other value, the behavior is undefined. 


If the program is compiled with LOCALETYPE(*LOCALEUCS2), the wide 
character properties are those defined by the LC_UCS2_CTYPE category of the 
current locale. 


Here are descriptions of each function in this group. 


iswalnum() 
Test for a wide alphanumeric character. 


iswalpha() 
Test for a wide alphabetic character, as defined in the alpha class of the 
LC_CTYPE category of the current locale. 


iswcntrl() 
Test for a wide control character, as defined in the cntrl class of the 
LC_CTYPE category of the current locale. 


iswdigit() 
Test for a wide decimal-digit character: 0 through 9, as defined in the digit 
class of the LC_CTYPE category of the current locale. 


iswgraph() 
Test for a wide printing character, not a space, as defined in the graph class 
of the LC_CTYPE category of the current locale. 


iswlower() 
Test for a wide lowercase character, as defined in the lower class of the 
LC_CTYPE category of the current locale or for which none of the 
iswentr1(), iswdigit(), iswspace() function are true. 


iswprint() 
Test for any wide printing character, as defined in the print class of the 
LC_CTYPE category of the current locale. 


iswpunct() 
Test for a wide non-alphanumeric, non-space character, as defined in the 
punct class of the LC_CTYPE category of the current locale. 


iswspace() 
Test for a wide whitespace character, as defined in the space class of the 
LC_CTYPE category of the current locale. 


iswupper() 
Test for a wide uppercase character, as defined in the upper class of the 
LC_CTYPE category of the current locale. 


iswxdigit() 
Test for a wide hexadecimal digit 0 through 9, a through f, or A through F. 
as defined in the xdigit class of the LC_CTYPE category of the current 
locale. 


The LC_CTYPE or LC_UCS2_TYPE category of the active locale determines the 
results returned from these functions. 


Note: The <wctype.h> functions are accessible only when 


LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) is specified on 
the compilation command. 
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Returned Value 


These functions return a nonzero value if the wide integer satisfies the test value, 
or a 0 value if it does not. The value for wc must be representable as a wide 
unsigned char. WEOF is a valid input value. 


The behavior of these wide-character functions is affected by the LC_CTYPE or 
LC_UCS2_TYPE category of the current locale. If you change the category, 
undefined results can occur. 


Example 


#include <stdio.h> 
#include <wctype.h> 


int main(void) 
{ 


int we; 


for (wc=0; wc <= OxFF; wct+) { 
printf ("%3d", wc); 
printf(" %#4x ", wc); 


( 
printf("%3s", iswalnum(wc) ? "AN" : ""); 
printf("%2s", iswalpha(wc) ? "A" : " "); 
printf("%2s", iswentrl(wc) ? "C" :" "); 
printf("%2s", iswdigit(wc) 2? "D" :"")s 
printf("%2s", iswgraph(wc) ? "G" : " "); 
printf("%2s", iswlower(wc) ? "L" : ""); 
printf(" %c", iswprint(wc) ? wo : ' ')3 
A iswpunct(wc) ? "PU" : " "); 
printf("%2s", iswspace(wc) ? "S" : " "); 
printf("%3s", iswprint(wc) ? "PR" : " "); 
printf("%2s", iswupper(wc) ? "U" : " "); 
printf("%2s", iswxdigit(wc) ? "X" : " "); 


putchar('\n'); 
} 


Related Information 


iswctype() — Test for Character Property 
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Format 


#include <wctype.h> 
int iswctype(wint_t wc, wctype_t wc_prop); 


Thread Safe: YES. 
Description 


The iswctype() function determines whether the wide character we has the 
property we_prop. If the value of we is neither WEOF nor any value of the wide 
characters that corresponds to a multibyte character, the behavior is undefined. If 
the value of we_prop is incorrect (that is, it is not obtained by a previous call to the 
wcetype() function, or we_prop has been invalidated by a subsequent call to the 
setlocale() function that has affected category LC_CTYPE or LC_UCS2_TYPE), 
the behavior is undefined. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


If the program is compiled with LOCALETYPE(*LOCALEUCS2), the wide 
character properties are those defined by the LC_UCS2_CTYPE category of the 


current locale. 


Note: This function is accessible only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


The iswctype() function returns true if the value of the wide character we has the 


property wce_prop. 


The following strings, alnum through to xdigit are reserved for the standard 
character classes. The functions are shown as follows with their equivalent isw*() 


function: 

iswctype(wc, wctype("alnum")); /* is equivalent to */ iswalnum(wc); 
iswctype(wc, wctype("alpha")); /* is equivalent to */ iswalpha(wc); 
iswctype(we, wctype("cntrl”)); /* is equivalent to */ iswentrl(wc); 

iswctype(we, wctype("digit”)); /* is equivalent to */ iswdigit(wc); 

iswctype(wc, wctype("graph")); /* is equivalent to */ iswgraph(we); 
iswctype(wc, wctype("lower”)); /* is equivalent to */ iswlower(we); 

iswctype(wc, wctype("print”)); /* is equivalent to */ iswprint(we); 

iswctype(wc, wctype("punct”)); /* is equivalent to */ iswpunct(we); 

iswctype(wc,wctype("space”)); /* is equivalent to */ iswspace(wc); 

iswctype(wc, wctype("upper”)); /* is equivalent to */ iswupper(we); 
iswctype(we, wctype("xdigit”)); /* is equivalent to */ iswxdigit(we); 


Example that uses iswctype() 


#include <stdio.h> 
#include <wctype.h> 


int main(void) 
{ 


int we; 


for (wc=0; wc <= 
printf ("%3d", 
printf(" %#4x 
printf ("%3s", 
printf ("%2s", 
printf("%2s", 
printf("%2s", 
printf("%2s", 
printf("%2s", 
printf(" %c", 
printf ("%3s", 
printf("%2s", 
printf ("%3s", 
printf("%2s", 
printf("%2s", 


putchar('\n'); 


} 


OxFF; wc++) { 


we) 5 

u ; wc) ; 

iswctype(wc, wctype("alnum")) ? "AN" : " "); 
iswctype(wc, wctype("alpha")) ? "A" : " "); 
iswctype(wc, wctype("cntr1")) ? "C" :" "js; 
iswctype(wc, wctype("digit")) ? "D" :" "); 
iswctype(wc, wctype("graph")) ? "G" : " "); 
iswctype(wc, wctype("lower")) ? "L" : " "); 
iswctype(wc, wctype("print")) ? we :' '); 
iswctype(wc, wctype("punct")) ? "PU" : " "); 
iswctype(wc, wctype("Sspace")) ? "S" : " "js; 
iswctype(wc, wctype("print")) ? "PR": " "); 
iswctype(wc, wctype("upper")) ? "U" : " "); 
iswctype(wc, wctype("xdigit")) ? "X" :" "); 


Related Information 
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_itoa - Convert Integer to String 


Format 


#include <stdlib.h> 
char *_itoa(int value, char «string, int radix); 


Note: The _itoa function is supported only for C++, not for C. 
Language Level: Extension 
Description 


_itoa() converts the digits of the given value to a character string that ends with a 
null character and stores the result in string. The radix argument specifies the base 

of value; it must be in the range 2 to 36. If radix equals 10 and value is negative, the 
first character of the stored string is the minus sign (-). 


Note: The space reserved for string must be large enough to hold the returned 
string. The function can return up to 33 bytes including the null character 
(\0). 


Return Value 
_itoa returns a pointer to string. There is no error return value. 
Example that uses _itoa() 


This example converts the integer value -255 to a decimal, a binary, and a hex 
number, storing its character representation in the array buffer. 


#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 
char buffer[35]; 
char *p; 
p = _itoa(-255, buffer, 10); 
printf("The result of _itoa(-255) with radix of 10 is %s\n", p); 
p = _itoa(-255, buffer, 2); 
printf("The result of _itoa(-255) with radix of 2\n is %s\n", p); 
p = _itoa(-255, buffer, 16); 
printf("The result of _itoa(-255) with radix of 16 is %s\n", p); 
return 0; 


} 


The output should be: 


The result of _itoa(-255) with radix of 10 is -255 
The result of _itoa(-255) with radix of 2 

is 11111111111111111111111100000001 
The result of _itoa(-255) with radix of 16 is ffffff0l 


Related Information: 


* Integer to String 
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¢ <stdlib.h> 


labs() — llabs() — Calculate Absolute Value of Long and Long Long 


Integer 


Format (labs ()) 


#include <stdlib.h> 
long int labs(long int n); 


Format (1]abs()) 
#include <stdlib.h> 


long long int llabs(long long int i); 

Language Level: ANSI 

Description 

The labs() function produces the absolute value of its long integer argument n. 
The result may be undefined when the argument is equal to LONG_MIN, the 
smallest available long integer. The value LONG_MIN is defined in the <limits.h> 
include file. 

The 1labs() function returns the absolute value of its long long integer 
operand.The result may be undefined when the argument is equal to 
LONG_LONG_MIN, the smallest available long integer. The value 
LONG_LONG_MIN is defined in the <limits.h> include file. 

Return Value 

The labs() function returns the absolute value of n. There is no error return value. 
The 1labs() function returns the absolute value of i. There is no error return value. 
Example that uses labs () 


This example computes y as the absolute value of the long integer -41567. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 


long x, Ys 
x = -41567L; 
y = labs(x); 


printf("The absolute value of %ld is %ld\n", x, y); 


[KEKKKKEKREKERKEKERKEKER Output should be similar to: ******kkkKKEKK 


The absolute value of -41567 is 41567 
x/ 


Related Information 
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Idexp() — Multiply by a Power of Two 


Format 

#include <math.h> 

double ldexp(double x, int exp); 

Language Level: ANSI 

Description 

The ldexp() function calculates the value of x * (2°). 

Return Value 

The Idexp() function returns the value of x*(2°?). If an overflow results, the 
function returns +HUGE_VAL for a large result or -HUGE_VAL for a small result, 
and sets errno to ERANGE. 

Example that uses |dexp() 


This example computes y as 1.5 times 2 to the fifth power (1.5*2°): 


#include <math.h> 
#include <stdio.h> 


int main(void) 


double x, y; 


int p; 

x = 1.5; 

p= 53 

y = ldexp(x,p)s 


printf("%lf times 2 to the power of %d is %1f\n", x, p, y)s 
} 


[KEKRKKEKRKEKERKEKER EKER Output should be similar to: **x****kk*kKKEKK 


1.500000 times 2 to the power of 5 is 48.000000 
x/ 


Related Information 


Idiv() — Ildiv() — Perform Long and Long Long Division 
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Format (ldiv()) 


#include <stdlib.h> 
ldiv_t ldiv(long int numerator, long int denominator); 


Format (11div()) 
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#include <stdlib.h> 
lldiv_t 1ldiv(long long int numerator, long long int denominator) ; 


Language Level: ANSI 


Thread Safe: YES. However, only the function version is thread safe. The macro 
version is NOT thread safe. 


Description 


The ldiv() function calculates the quotient and remainder of the division of 
numerator by denominator. 


Return Value 


The Idiv() function returns a structure of type ldiv_t, containing both the quotient 
(long int quot) and the remainder (long int rem). If the value cannot be 
represented, the return value is undefined. If denominator is 0, an exception is 
raised. 


The 1]div() subroutine computes the quotient and remainder of the numerator 
parameter by the denominator parameter. 


The 11div() subroutine returns a structure of type Ildiv_t, containing both the 
quotient and the remainder. The structure is defined as: 


struct lldiv_t 


{ 
long long int quot; /* quotient */ 
long long int rem; /* remainder */ 


If the division is inexact, the sign of the resulting quotient is that of the algebraic 
quotient, and magnitude of the resulting quotient is the largest long long integer 
less than the magnitude of the algebraic quotient. If the result cannot be 
represented (for example, if the denominator is 0), the behavior is undefined. 


Example that uses Idiv() 


This example uses ldiv() to calculate the quotients and remainders for a set of 
two dividends and two divisors. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 
long int num[2] = {45,-45}; 
long int den[2] = {7,-7}; 
ldiv_t ans; /* ldiv_t is a struct type containing two long ints: 
"quot' stores quotient; 'rem' stores remainder */ 
short i,j; 
printf("Results of long division:\n"); 
for (i = 03; i < 2; i++) 
for (j = 0; j < 2; j++) 
ans = ldiv(num[i], den[j]); 
printf("Dividend: %61d Divisor: %61d", num[i], den[j]); 
printf(" Quotient: %61d Remainder: %61d\n", ans.quot, ans.rem); 
} 
[KEKRKKERKEKERKEKERKEKREK Expected OUtPUL: kee RK RRA RA REAR RRR RRR ERR 


Results of long division: 

Dividend: 45 Divisor: 7 Quotient: 6 Remainder: 3 
Dividend: 45 Divisor: -7 Quotient: -6 Remainder: 3 
Dividend: -45 Divisor: 7 Quotient: -6 Remainder: -3 
Dividend: -45 Divisor: -7 Quotient: 6 Remainder: -3 
* 

/ 


Related Information 


localeconv() — Retrieve Information from the Environment 


Format 
#include <locale.h> 


struct lconv *localeconv(void); 

Language Level: ANSI 

Description 

The localeconv() sets the components of a structure having type struct conv to 
values appropriate for the current locale. The structure may be overwritten by 
another call to localeconv(), or by calling the setlocale()function and passing 


LC_ALL, LC_UCS2_ALL, LC_MONETARY, or LC_NUMERIC. 


The structure contains the following elements (defaults shown are for the C locale): 


Element Purpose of Element Default 


mor 


char *decimal_point Decimal-point character used to format 
non-monetary quantities. 


char *thousands_sep Character used to separate groups of 
digits to the left of the decimal-point 
character in formatted non-monetary 
quantities. 


158 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Element 


Purpose of Element 


Default 


char *grouping 


String indicating the size of each group 
of digits in formatted non-monetary 
quantities. Each character in the string 
specifies the number of digits in a 
group. The initial character represents 
the size of the group immediately to 
the left of the decimal delimiter. The 
characters following this define 
succeeding groups to the left of the 
previous group. If the last character is 
not UCHAR_MAX, the grouping is 
repeated using the last character as the 
size. If the last characater is 
UCHAR_MAX, grouping is only 
performed for the groups already in 
the string (no repetition). See fable Lod 

for an example of how 
grouping works. 


char *int_curr_symbol 


International currency symbol for the 
current locale. The first three characters 
contain the alphabetic international 
currency symbol. The fourth character 
(usually a space) is the character used 
to separate the international currency 
symbol from the monetary quantity. 


char *currency_symbol 


char *mon_decimal_point 


Local currency symbol of the current 
locale. 


Decimal-point character used to format 
monetary quantities. 


wn 


wn 


char *mon_thousands_sep 


Separator for digits in formatted 
monetary quantities. 


wn 


char *mon_grouping 


String indicating the size of each group 
of digits in formatted monetary 
quantities. Each character in the string 
specifies the number of digits in a 
group. The initial character represents 
the size of the group immediately to 
the left of the decimal delimiter. The 
following characters define succeeding 
groups to the left of the previous 
group. If the last character is not 
UCHAR_MAX, the grouping is 
repeated using the last character as the 
size. If the last character is 
UCHAR_MAX, grouping is only 
performed for the groups already in 
the string (no repetition). See fable Lod 

for an example of how 
grouping works. 


wn 


char *positive_sign 


String indicating the positive sign used 
in monetary quantities. 


wn 


char *negative_sign 


String indicating the negative sign used 
in monetary quantities. 


wn 
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Element 


Purpose of Element 


Default 


char int_frac_digits 


The number of displayed digits to the 
right of the decimal place for 
internationally formatted monetary 
quantities. 


UCHAR_MAX 


char frac_digits 


Number of digits to the right of the 
decimal place in monetary quantities. 


UCHAR_MAX 


char p_cs_precedes 


1 if the currency_symbol precedes the 
value for a nonnegative formatted 
monetary quantity; 0 if it does not. 


UCHAR_MAX 


char p_sep_by_space 


1 if the currency_symbol is separated 
by a space from the value of a 
nonnegative formatted monetary 
quantity; 0 if it does not. 


UCHAR_MAX 


char n_cs_precedes 


1 if the currency_symbol precedes the 
value for a negative formatted 
monetary quantity; 0 if it does not. 


UCHAR_MAX 


char n_sep_by_space 


1 if the currency_symbol is separated 
by a space from the value of a negative 
formatted monetary quantity; 0 if it 
does not. 


UCHAR_MAX 


char p_sign_posn 


Value indicating the position of the 
positive_sign for a nonnegative 
formatted monetary quantity. 


UCHAR_MAX 


char n_sign_posn 


Value indicating the position of the 
negative_sign for a negative formatted 
monetary quantity. 


UCHAR_MAX 


Pointers to strings with a value of 


un 


indicate that the value is not available in the 


C locale or is of zero length. Elements with char types with a value of 
UCHAR_MAxX indicate that the value is not available in the current locale. 


The n_sign_posn and p_sign_posn elements can have the following values: 


Value Meaning 


0 The quantity and currency_symbol are enclosed in parentheses. 
1 The sign precedes the quantity and currency_symbol. 

2 The sign follows the quantity and currency_symbol. 

3 The sign precedes the currency_symbol. 

4 The sign follows the currency_symbol. 


Grouping Example 
Table 1. Grouping Example 


Locale Source Grouping String Number Formatted Number 
-1 0x00 123456789 123456789 

3 0x0300 123456789 123,456,789 

3;-1 Ox03FFO0 123456789 123456,789 

3;2;1 0x03020100 123456789 1,2,3,4,56,789 
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Monetary Formatting Example: 


Table 2. Monetary Formatting Example 


Country Positive Format Negative Format International Format 
Italy L.1.230 -L.1.230 ITL.1.230 
Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56 
Norway kr1.234,56 kr1.234,56- NOK1.234,56 
Switzerland SFRs. 1,234.56 SFrx.1,234.56C CHF 1,234.56 


The above table was generated by locales withe the following monetary fields: 


Table 3. Monetary Fields 


Italy 


Netherlands 


Norway 


Switzerland 


int_curr_symbol 


” TTL. ” 


"NLG" 


"NOK" 


"CHE" 


currency_symbol 


nT ” 


A 


"kr" 


"SFrs.” 


mon_decimal_point 


wn 


nw 
y 


wn 
y 


wn 


mon_thousands_sep 


wn 


ww 


ww 


wn 
y 


mon_grouping 


WN BH 


WN gi 


NBN 


W"\ 3" 


positive_sign 


wn 


wn 


wn 


on 


negative_sign 


non 


now 


now 


id 


int_frac_digits 


frac_digits 


p_cs_precedes 


p_sep_by_space 


n_cs_preceds 


n_sep_by_space 


p_sep_posn 


n_sign_posn 


Return Value 


Sele; olreslolresloao|;o 


Ble tet et ele |lNniln 


N/R [| Ole | oOolrResINniN 


The localeconv() function returns a pointer to the structure. 


Example that uses *CLD locale objects 


This example prints out the default decimal point for your locale and then the 
decimal point for the LC_C_FRANCE locale. 
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#include <stdio.h> 
#include <locale.h> 


int main(void) { 


char * string; 
struct lconv * mylocale; 
mylocale = localeconv(); 


/* Display default decimal point «/ 
printf("Default decimal point is a %s\n", mylocale->decimal_point) ; 


if (NULL != (string = setlocale(LC_ALL, LC_C_FRANCE))) { 
mylocale = localeconv(); 


/* A comma is set to be the decimal point when the locale is LC_C_FRANCE*/ 
printf("France's decimal point is a %s\n", mylocale->decimal_point); 
} else { 


printf("setlocale(LC_ALL, LC_C_FRANCE) returned <NULL>\n") ; 
} 
return 0; 


} 
Example that uses *LOCALE objects 


[KEKE KKK RIKER IKK A KKK KEIR KERIKERI KEIRA KKK AKI KKK AKER AK REA AKER KK 
This example prints out the default decimal point for 

the C locale and then the decimal point for the French 

locale using a *LOCALE object called 
"QSYS.LIB/MYLIB.LIB/LC_FRANCE.LOCALE". 


Step 1: Create a French «LOCALE object by entering the command 
CRTLOCALE LOCALE('QSYS.LIB/MYLIB.LIB/LC_FRANCE.LOCALE') + 
SRCFILE('QSYS.LIB/QSYSLOCALE.LIB/QLOCALESRC.FILE/ + 
FR_FR.MBR') CCSID(297) * 
Step 2: Compile the following C source, specifying 
LOCALETYPE(*LOCALE) on the compilation command. 
Step 3: Run the program. 


KR KKK A KKK AK KKK KKK KKK KK KKK KKK KK KHAKI KKK IKKE KKK KAKA AREA KER AKER | 


#include <stdio.h> 
#include <locale.h> 
int main(void) { 
char * string; 
struct lconv * mylocale; 
mylocale = localeconv(); 


/* Display default decimal point «/ 
printf("Default decimal point is a %s\n", mylocale->decimal_point); 
if (NULL != (string = setlocale(LC_ALL, 
"QSYS.LIB/MYLIB.LIB/LC_FRANCE.LOCALE"))) { 
mylocale = localeconv(); 


/* A comma is set to be the decimal point in the French locale */ 
printf("France's decimal point is a %s\n", mylocale->decimal_point) ; 
} else { 
printf("setlocale(LC_ALL, \"QSYS.LIB/MYLIB.LIB/LC_FRANCE.LOCALE\") \ 
returned <NULL>\n") ; 
} 


return 0; 
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Related Information 


localtime() — Convert Time 


Format 


#include <time.h> 
struct tm *localtime(const time_t *timeval); 


Language Level: ANSI 
Thread Safe: NO. Use localtime_r() instead. 
Description 


The localtime() function converts a time value, in seconds, to a structure of type 
tm. 


Note: This function is locale sensitive. 


The localtime() function breaks down timeval, corrects for the local time zone and 
Daylight Saving Time, if appropriate, and stores the corrected time in a structure of 


type tm. 


The time value is usually obtained by a call to the time() function. 


Note: 


* The gmtime() and localtime() functions may use a common, statically 
allocated buffer for the conversion. Each call to one of these functions 
may destroy the result of the previous call. The ctime_r(), gmtime_r(), 
and localtime_r() functions do not use a common, statically-allocated 
buffer. These functions can be used in the place of the asctime(), ctime(), 
gmtime() and localtime() functions if reentrancy is desired. 


* Calendar time is the number of seconds that have elapsed since EPOCH, 
which is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 


* On the iSeries, the time() function uses the QUTCOFFSET system value 
for calculating UTC. The QUTCOFFSET value specifies the difference in 
hours and minutes between UTC, also known as Greenwich mean time, 
and the current system time. You can override the QUTCOFFSET value by 
specifying the TZDIFF and TZNAME category of the current locale. 

Return Value 


The localtime() function returns a pointer to the structure result. There is no error 
return value. 


Example that uses localtime() 


This example queries the system clock and displays the local time. 
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#include <time.h> 
#include <stdio.h> 


int main(void) 


struct tm *newtime; 
time_t ltime; 


time(localtime()); 
newtime = localtime(localtime()); 
printf("The date and time is %s", asctime(newtime) ); 


} 


[xxxxxkxxxxxeee If the local time is 3:00 p.m. May 31, 1993, x*xxxxxxxxx 
KRKKKEKKKKKRKKKREKEREKERE OUTPUT SHOUId De:  *KKKKKKKKKKKKKKKKKEKKER 


The date and time is Mon May 31 15:00:00 1993 
x/ 


Related Information 


localtime_r() — Convert Time (Restartable) 


164 


Format 


#include <time.h> 
struct tm *localtime_r(const time_t *timeval, struct tm *result); 


Description 
This function is the restartable version of localtime(). 


The localtime_r() function converts a time value, in seconds, to a structure of 
type tm. 


The localtime_r() function breaks down timeval, corrects for the local time zone 
and Daylight Saving Time, if appropriate, and stores the corrected time in a 
structure of type tm. 


The time value is usually obtained by a call to the time() function. 


Notes: 


1. Calendar time is the number of seconds that have elapsed since EPOCH, which 
is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 


2. On the iSeries, the time() function uses the QUTCOFFSET system value for 
calculating UTC. The QUTCOFFSET value specifies the difference in hours and 
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minutes between UTC, also known as Greenwich mean time, and the current 
system time. You can override the QUTCOFFSET value by specifying the 
TZDIFF and TZNAME category of the current locale. 


Return Value 


The localtime_r() returns a pointer to the structure result. There is no error return 
value. 


Example that uses localtime_r() 
This example queries the system clock and displays the local time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 
struct tm newtime; 
time_t ltime; 
char buf[50]; 


time(localtime()); 
localtime_r(localtime(), &newtime) ; 
printf("The date and time is %s", asctime_r(&newtime, buf)); 


} 


/xxxxexexeeeeee If the local time is 3:00 p.m. May 31, 1993, *#*#eeeeHx 
KRKRKKKKEKREKERERERERERERER OUTPUT Should be: x*xxKKKKKKKKKKKEKKKERK 


The date and time is Mon May 31 15:00:00 1993 
*/ 


Related Information 


log() — Calculate Natural Logarithm 
Format 
#include <math.h> 
double log(double x); 
Language Level: ANSI 


Description 


The log() function calculates the natural logarithm (base e) of x. 
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Return Value 


The log() function returns the computed value. If x is negative, 1og()sets errno to 
EDOM and may return the value -HUGE_VAL. If x is zero, 1og() returns the value 
-HUGE_VAL, and may set errno to ERANGE. 


Example that uses 10g() 
This example calculates the natural logarithm of 1000.0. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
double x = 1000.0, y; 
y = log(x); 


printf("The natural logarithm of %1f is %lf\n", x, y)3 
} 


[KEKRKKEREKERKEKERERER Output should be similar to: ******kk*kKKEKK 


The natural logarithm of 1000.000000 is 6.907755 
*/ 


Related Information 


° [‘<math.h>” on page 8 


log10() — Calculate Base 10 Logarithm 
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Format 

#include <math.h> 

double log10(double x); 

Language Level: ANSI 

Description 

The 10g10() function calculates the base 10 logarithm of x. 

Return Value 

The 10g10() function returns the computed value. If x is negative, 10g10()sets 
errno to EDOM and may return the value -HUGE_VAL. If x is zero, the 10g10() 
function returns the value -HUGE_VAL, and may set errno to ERANGE. 
Example that uses 10g10() 


This example calculates the base 10 logarithm of 1000.0. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 

{ 
double x = 1000.0, y; 
y = 10g10(x); 


printf("The base 10 logarithm of %1f is %lf\n", x, y)3 
} 


[ KEKRKKEKRKEKERKEKERERER Output should be similar to: ******kk*kKKEKK 


The base 10 logarithm of 1000.000000 is 3.000000 
x/ 


Related Information 


_lItoa - Convert Long Integer to String 


Format 


#include <stdlib.h> 
char *_ltoa(long value, char «string, int radix); 


Note: The _ltoa function is supported only for C++, not for C. 
Language Level: Extension 
Description 


_ltoa converts the digits of the given long integer value to a character string that 
ends with a null character and stores the result in string. The radix argument 
specifies the base of value; it must be in the range 2 to 36. If radix equals 10 and 
value is negative, the first character of the stored string is the minus sign (-). 


Note: The space allocated for string must be large enough to hold the returned 
string. The function can return up to 33 bytes including the null character 
(\0). 


Return Value 
_|toa returns a pointer to string. There is no error return value. 
Example that uses _1toa() 


This example converts the integer value -255L to a decimal, a binary, and a hex 
value, and stores its character representation in the array buffer. 
#include <stdio.h> 
#include <stdlib.h> 
int main(void) 
{ 
char buffer[35]; 
char *p; 
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p = _ltoa(-255L, buffer, 10); 

printf("The result of _ltoa(-255) with radix of 10 is %s\n", p); 

p = _itoa(-255L, buffer, 2); 

printf("The result of _ltoa(-255) with radix of 2\n is %s\n", p); 
p = _itoa(-255L, buffer, 16); 

printf("The result of _ltoa(-255) with radix of 16 is %s\n", p); 
return 0; 


} 


The output should be: 


The result of _ltoa(-255) with radix of 10 is -255 
The result of _ltoa(-255) with radix of 2 

is 11111111111111111111111100000001 
The result of _ltoa(-255) with radix of 16 is ffffff0l 


Related Information: 
* atol 


* westol 
° <stdlib.h> 


longjmp() — Restore Stack Environment 


Format 


#include <setjmp.h> 
void longjmp(jmp_buf env, int value); 


Language Level: ANSI 
Description 


The longjmp() function restores a stack environment previously saved in env by 
the setjmp() function. The setjmp() and longjmp() functions provide a way to 
perform a non-local goto. They are often used in signal handlers. 


A call to the setjmp() function causes the current stack environment to be saved in 
env. A subsequent call to longj mp() restores the saved environment and returns 
control to a point in the program corresponding to the setjmp()call. Processing 
resumes as if the setjmp() call had just returned the given value. 


All variables (except register variables) that are accessible to the function that 
receives control contain the values they had when longjmp() was called. The 
values of register variables are unpredictable. Nonvolatile auto variables that are 
changed between calls to the setjmp() and longjmp() functions are also 
unpredictable. 


Note: Ensure that the function that calls the setjmp() function does not return 
before you call the corresponding longjmp() function. Calling longjmp() 
after the function calling the setjmp() function returns causes unpredictable 
program behavior. 


The value argument must be nonzero. If you give a zero argument for value, 
longjmp() substitutes 1 in its place. 
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Return Value 


The longjmp() function does not use the normal function call and return 
mechanisms; it has no return value. 


Example that uses longjmp() 
This example saves the stack environment at the statement: 
if(setjmp(mark) != 0) ... 


When the system first performs the if statement, it saves the environment in mark 
and sets the condition to FALSE because the setjmp() function returns a 0 when it 
saves the environment. The program prints the message: 


setjmp has been called 


The subsequent call to function p() tests for a local error condition, which can 
cause it to call the longjmp() function. Then, control returns to the original 
setjmp() function using the environment saved in mark. This time, the condition is 
TRUE because -1 is the return value from the longjmp() function. The example 
then performs the statements in the block, prints longjmp() has been called, calls 
the recover() function, and leaves the program. 
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#include <stdio.h> 
#include <setjmp.h> 
#include <stdlib.h> 


jmp_buf mark; 


void p(void); 
void recover(void); 


int main(void) 
if (setjmp(mark) != 0) 


printf("longjmp has been called\n"); 
recover(); 
exit(1); 


printf("setjmp has been called\n"); 
printf("Calling function p()\n"); 

p(); 

printf("This point should never be reached\n"); 


} 
void p(void) 


printf("Calling longjmp() from inside function p()\n"); 
longjmp(mark, -1); 
printf("This point should never be reached\n") ; 


} 
void recover(void) 


printf("Performing function recover()\n"); 


} 


[kkeKK KARR RARE ER OUtDUE should be aS fOlIOWS: *XXKKRKEKKKKKKKKKEKKEKE 
setjmp has been called 

Calling function p() 

Calling longjmp() from inside function p() 

longjmp has been called 


Performing function recover() 
KKK KKK KKK KEKE AK KEK KKK IKEA KKK AK KEK KK AK KKK KEK AKI IKKE AKER AEE AA KER | 


Related Information 


malloc() — Reserve Storage Block 
Format 
#include <stdlib.h> 
void *malloc(size_t size); 
Language Level: ANSI 
Thread Safe: YES 


Description 


The malloc() function reserves a block of storage of size bytes. Unlike the calloc() 
function, malloc() does not initialize all elements to 0. 
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Notes: 


1. 


To use Teraspace storage instead of heap storage without changing the C source 
code, specify the TERASPACE(*YES *TSIFC) parameter on the CRTCMOD 
compiler command. This maps the malloc() library function to _C_TS_malloc(), 
its Teraspace storage counterpart. The maximum amount of Teraspace storage 
that can be allocated by each call to _C_TS_malloc() is 2GB - 224, or 2147483424 
bytes. If more than 2147483408 bytes are needed on a single request, call 
_C_TS_malloc64(unsigned long long int)s;. 

For more information, see the ILE Concepts manual. 


For current statistics on the teraspace storage being used by MI programs in an 
activation group, call the _C_TS_malloc_info function. This function returns 
information including total bytes, allocated bytes and blocks, unallocated bytes 
and blocks, requested bytes, pad bytes, and overhead bytes. To get more 
detailed information about the memory structures used by the _C_TS_malloc() 
and _C_TS_malloc64() functions, call the _C_TS_malloc_debug function. You can 
use the information this function returns to identify memory corruption 
problems. 


Return Value 


The malloc() function returns a pointer to the reserved space. The storage space to 
which the return value points is suitably aligned for storage of any type of object. 
The return value is NULL if not enough storage is available, or if size was specified 
as Zero. 


Example that uses malloc() 


This example prompts for the number of array entries you want and then reserves 
enough space in storage for the entries. If malloc() was successful, the example 
assigns values to the entries and prints out each entry; otherwise, it prints out an 
error. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


long * array; /* start of the array */ 


long * index; /* index variable x/ 
int i; /* index variable */ 
int num; /* number of entries of the array */ 


printf( "Enter the size of the array\n" ); 
scanf( "%i", &num ); 


/* allocate num entries */ 
if ( (index = array = (long *) malloc( num * sizeof( long ))) != NULL ) 


{ 
for (i = 0; i < num; ++i ) /* put values in array */ 
*indextt+ = i; /* using pointer notation */ 
for (i = 0; i < num; ++i ) /* print the array out */ 


printf( "array[ %i ] = %i\n", i, array[i] ); 


else { /* malloc error */ 
perror( "Out of storage" ); 
abort(); 
} 
} 


[KEKKKKERKEKERKEKERKEKER Output should be similar tO: **x****kkkkKKEKK 


Enter the size of the array 
array[ 0 ] = 0 

array[ 1 
array[ 2 
array[ 3 
array[ 4 


*/ 


J=1 
]=2 
] =3 
]=4 


Related Information 


mblen() — Determine Length of a Multibyte Character 
Format 
#include <stdlib.h> 
int mblen(const char *string, size_t n); 
Language Level: ANSI 
Thread Safe: NO. Use mbrlen() instead. 


Description 


The mblen() function determines the length in bytes of the multibyte character 
pointed to by string. A maximum of n bytes is examined. 


Return Value 
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If string is NULL, the mblen() function returns: 


* Non-zero if the active locale allows mixed-byte strings. The function initializes 
the state variable. 


¢« Zero otherwise. 


If string is not NULL, mblen() returns: 

* Zero if string points to the null character. 

¢ The number of bytes comprising the multibyte character. 
* -1 if string does not point to a valid multibyte character. 


Note: The mblen(), mbtowc(), and wctomb() functions use their own statically 
allocated storage and are therefore not restartable. However, mbrlen(), 
mbrtowc(), and wcrtomb() are restartable. 


Example that uses mblen() 


This example uses mblen() and mbtowc() to convert a multibyte character into a 
single wide character. 


#include <stdio.h> 
#include <stdlib.h> 


int length, temp; 
char string [6] = "w"; 
wchar_t arr[6]; 


int main(void) 


{ 


/* Initialize internal state variable «/ 
length = mblen(NULL, MB_CUR MAX); 


/* Set string to point to a multibyte character */ 
length = mblen(string, MB_CUR_MAX); 

temp = mbtowc(arr,string, length) ; 

printf("wide character string: arr[1] = L'\0';",arr); 


} 


Related Information 


mbrlen() — Determine Length of a Multibyte Character (Restartable) 


Format 
#include <wchar.h> 
size_t mbrlen (const char *s, size_t n, mbstate_t *ps); 


Language Level: ANSI 
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Description 

This function is the restartable version of mblen(). 

The mbrlen() function determines the length of a multibyte character. 
n is the number of bytes (at most) of the multibyte string to examine. 


This function differs from its corresponding internal-state multibyte character 
function in that it has an extra parameter, ps of type pointer to mbstate_t that 
points to an object that can completely describe the current conversion state of the 
associated multibyte character sequence. If ps is a NULL pointer, mbrlen() behaves 
like mblen(). 


mbrlen() is a restartable version of mblen(). In other words, shift-state information 
is passed as one of the arguments (ps represents the initial shift) and is updated on 
exit. With mbrlen(), you can switch from one multibyte string to another, provided 
that you have kept the shift-state information. 


This function is affected by the LC_CTYPE of the current locale. 


Note: This function is only accessible when you specify LOCALETYPE(*LOCALE) 
or LOCALETYPE(*LOCALEUCS2) on the compilation command. 


Return Value 


If s is a null pointer, if the active locale allows mixed-byte strings, and if the active 
locale initializes the state variabe, the mbrlen() function returns nonzero. If the 
active locale does not allow mixed byte strings, zero will be returned. 


If s is not a null pointer, the mbrlen() function returns one of the following: 

0 If s is a NULL string (s points to the NULL character). 

positive 
If the next n or fewer bytes comprise a valid multibyte character. The value 
returned is the number of bytes that comprise the multibyte character. 


(size_t)-1 
If s does not point to a valid multibyte character. 


(size_t)-2 
If the next n or fewer bytes contribute to an incomplete but potentially 
valid character and all n bytes have been processed 


Example that uses mbrlen() 


/* This program is compiled with LOCALETYPE(*LOCALE) and */ 
/* SYSIFCOPT(*IFSIO) */ 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
#include <wchar.h> 
#include <errno.h> 


#define LOCNAME "qsys.1ib/JA_JP.locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 


{ 
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int length, sl = 0; 

char string[10]; 
mbstate_t ps = Q; 
memset(string, '\0', 10); 


string[0] = OxC1; 
string[1] = Ox0E; 
string[2] = 0x41; 
string[3] = 0x71; 
string[4] = 0x41; 
string[5] = 0x72; 
string[6] = OxOF; 
string[7] = O0xC2; 
/* In this first example we will find the length of x/ 
/* of a multibyte character when the CCSID of locale */ 
/* associated with LC_CTYPE is 37. x/ 
/* For single byte cases the state will always */ 
/* remain in the initial state 0 */ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 


length = mbrlen(string, MB_CUR_MAX, &ps); 


/* In this case length is 1, which is always the case for */ 
/* single byte CCSID */ 


printf("length = %d, state = %d\n\n", length, ps); 
printf ("MB CUR_MAX: %d\n\n", MB_CUR MAX); 


/* Now lets try a multibyte example. We first must set the */ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = mbrlen(string, MB_CUR_MAX, &ps); 


/* The first is single byte so length is 1 and */ 
/* the state is still the initial state 0 */ 


printf("length = %d, state = %d\n\n", length, ps); 
printf ("MB CUR_MAX: %d\n\n", MB_CUR MAX); 


sl] += length; 


length = mbrlen(&string[s1], MB_CUR MAX, &ps); 


/* The next character is a mixed byte. Length is 3 to */ 
/* account for the shiftout Ox0e. State is x/ 
/* changed to double byte state. x/ 


printf("length = %d, state = %d\n\n", length, ps); 


sl] += length; 


length = mbrlen(&string[s1], MB CUR MAX, &ps); 


/* The next character is also a double byte character. */ 
/* The state is changed to initital state since this was */ 
/* the last double byte character. Length is 3 to */ 
/* account for the ending OxOf shiftin. */ 


printf("length = %d, state = %d\n\n", length, ps); 


sl] += length; 
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length = mbrlen(&string[s1], MB_CUR_MAX, &ps); 


/* The next character is single byte so length is 1 and */ 
/* state remains in initial state. x/ 


printf("length = %d, state = %d\n\n", length, ps); 


} 
/* The output should look like this: 


length = 1, state = 0 

MB_CUR_MAX: 1 

length = 1, state = 0 

MB_CUR MAX: 4 

length = 3, state = 2 

length = 3, state = 0 

length = 1, state = 0 

*/ 

* * * End of File * * * 


Related Information 


mbrtowc() — Convert a Multibyte Character to a Wide Character 


(Restartable) 


Format 


#include <wchar.h> 
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps); 


Description 
This function is the restartable version of the mbtowc() function. 


If s is a null pointer, the mbrtowc() function determines the number of bytes 
necessary to enter the initial shift state (zero if encodings are not state-dependent 
or if the initial conversion state is described). In this situation, the value of the pwc 
parameter will be ignored and the resulting shift state described will be the initial 
conversion state. 
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If s is not a null pointer, the mbrtowc() function determines the number of bytes 
that are in the multibyte character (and any leading shift sequences) pointed to by 
s, produces the value of the corresponding multibyte character and if pwc is not a 
null pointer, stores that value in the object pointed to by pwc. If the corresponding 
multibyte character is the null wide character, the resulting state will be reset to 
the initial conversion state. 


This function differs from its corresponding internal-state multibyte character 
function in that it has an extra parameter, ps of type pointer to mbstate_t that points 
to an object that can completely describe the current conversion state of the 
associated multibyte character sequence. If ps is NULL, this function uses an 
internal static variable for the state. 


At most, 1 bytes of the multibyte string are examined. 


Note: If the program is compiled with LOCALETYPE(*LOCALEUCS2), this 
function is accessible, but UNICODE is not supported at this time. It will 
behave as if it were compiled with LOCALETYPE(*LOCALE). 


This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


If s is a null pointer, the mbrtowc() function returns the number of bytes necessary 
to enter the initial shift state. The value returned must be less than the 
MB_CUR_MAX macro. 


If s is not a null pointer, the mbrtowc() function returns one of the following: 


0 If the next n or fewer bytes form the multibyte character that corresponds 
to the null wide character. 


positive 
If the next n or fewer bytes form a valid multibyte character. The value 
returned is the number of bytes that constitute the multibyte character. 


(size_t)-2 
If the next n bytes form an incomplete (but potentially valid) multibyte 
character, and all n bytes have been processed. It is unspecified whether 
this can occur when the value of 1 is less than the value of the 
MB_CUR_MAX macro. 


(size_t)-1 
If an encoding error occurs (when the next 1 or fewer bytes do not form a 
complete and correct multibyte character). The value of the macro EILSEQ 
is stored in errno, but the conversion state is unchanged. 


Note: When a -2 value is returned, the string would contain redundant shift-out 
and shift-in characters. To continue processing the multibyte string, 
increment the pointer by the value n, and call mbrtowc() again. 


Example that uses mbrtowc() 


/* This program is compiled with LOCALETYPE(*LOCALE) and = */ 
/* SYSIFCOPT(*IFSIO) x/ 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
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#include <wchar.h> 
#include <errno.h> 


#define LOCNAME  "/qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "/qsys.1ib/EN_US.1ocale" 


int main(void) 

{ 
int length, sl = 0; 
char string[10]; 
wchar_t buffer[10]; 
mbstate_t ps = 0; 
memset(string, '\O', 10); 


string[0] = 0xC1; 
string[1] = OxOE; 
string[2] = 0x41; 
string[3] = 0x71; 
string[4] = 0x41; 
string[5] = 0x72; 
string[6] = OxOF; 
string[7] = OxC2; 
/* In this first example we will convert x/ 
/* a multibyte character when the CCSID of locale */ 
/* associated with LC_CTYPE is 37. x/ 
/* For single byte cases the state will always */ 
/* remain in the initial state 0 x/ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 


length = mbrtowc(buffer, string, MB_CUR_MAX, &ps); 


+ 


/* In this case length is 1, and Cl is converted 0x00C1 / 


printf("length = %d, state = %d\n\n", length, ps); 
printf("MB_CUR_MAX: %d\n\n", MB_CUR MAX); 


/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = mbrtowc(buffer, string, MB_CUR_MAX, &ps); 

/* The first is single byte so length is 1 and */ 
/* the state is still the initial state 0. Cl is converted*/ 
/* to Ox00C1 x/ 


printf("length = %d, state = %d\n\n", length, ps); 
printf ("MB CUR_MAX: %d\n\n", MB_CUR_MAX); 


sl] += length; 

length = mbrtowc(&buffer[1], &string[s1], MB_CUR_MAX, &ps); 
/* The next character is a mixed byte. Length is 3 to */ 
/* account for the shiftout Ox0e. State is x/ 
/* changed to double byte state. 0x4171 is copied into */ 
/* the buffer */ 


printf("length = %d, state = %d\n\n", length, ps); 


sl] += length; 
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length = mbrtowc(&buffer[2], &string[s1], MB_CUR_MAX, &ps); 


/* The next character is also a double byte character. */ 
/* The state is changed to initial state since this was */ 
/* the last double byte character. Length is 3 to */ 


/* account for the ending OxOf shiftin. 0x4172 is copied */ 
/* into the buffer. */ 


printf("length = %d, state = %d\n\n", length, ps); 

sl] += length; 

length = mbrtowc(&buffer[3], &string[s1], MB_CUR_MAX, &ps); 
/* The next character is single byte so length is 1 and */ 
/* state remains in initial state. @xC2 is converted to */ 
/* 0x00C2. The buffer now has the value: */ 
/* 0x00C14171417200C2 */ 


printf("length = %d, state = %d\n\n", length, ps); 


2 The output should look like this: 
length = 1, state = 0 

MB_CUR_MAX: 1 

length = 1, state = 0 

MB_CUR_MAX: 4 

length = 3, state = 2 

length = 3, state = 0 

length = 1, state = 0 


*/ 


Related Information 


mbsinit() — Test State Object for Initial State 


Format 
#include <wchar.h> 
int mbsinit (const mbstate_t *ps); 


Description 
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If ps is not a null pointer, the mbsinit() function specifies whether the pointed to 
mbstate_t object describes an initial conversion state. 


Note: This function is only accessible if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


The mbsinit() function returns nonzero if ps is a null pointer or if the pointed to 
object describes an initial conversion state. Otherwise, it returns zero. 


Example that uses mbsinit() 


This example checks the conversion state to see if it is the initial state. 


#include <stdio.h> 
#include <wchar.h> 
#include <stdlib.h> 


main() 

{ 
char «string = "ABC"; 
mbstate_t state = 0; 
wchar_t wc; 
int rc; 


rc = mbrtowc(&wc, string, MB _CUR_MAX, &state); 
if (mbsinit(&state) ) 
printf("In initial conversion state\n"); 


} 


Related Information 


mbsrtowcs() — Convert a Multibyte String to a Wide Character String 


(Restartable) 


Format 


#include <wchar.h> 
size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len, 
mbstate_t *ps); 


Thread Safe: YES, if ps is not NULL. 
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Description 
This function is the restartable version of mbstowcs(). 


The mbsrtowcs() function converts a sequence of multibyte characters that begins 
in the conversion state described by ps from the array indirectly pointed to by src 
into a sequence of corresponding wide characters. It then stores the converted 
characters into the array pointed to by dst. 


Conversion continues up to and including an ending null character, but the ending 
null wide character will not be stored. Conversion will stop earlier in two cases: 
when a sequence of bytes are reached that do not form a valid multibyte character, 
or (if dst is not a null pointer) when Jen wide characters have been stored into the 
array pointed to by dst. Each conversion takes place as if by a call to mbrtowc() 
function. 


If dst is not a null pointer, the pointer object pointed to by src will be assigned 
either a null pointer (if conversion stopped due to reaching an ending null 
character) or the address just past the last multibyte character converted. If 
conversion stopped due to reaching an ending null character, the initial conversion 
state is described. 


The behavior of mbsrtowcs() is affected by the LC_CTYPE category of the current 
locale. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


If the program is compiled LOCALETYPE(**LOCALEUCS2), this function 
will behave the same as if it were compiled with LOCALETYPE(*LOCALE), 
since UCS2 is not supported by this function. 


Return Value 


If the input string does not begin with a valid multibyte character, an encoding 
error occurs, the mbsrtowcs() function stores the value of the macro EILSEQ in 
errno, and returns (size_t) -1, but the conversion state will be unchanged. 
Otherwise, it returns the number of multibyte characters successfully converted, 
which is the same as the number of array elements modified when dst is not a null 
pointer. 


Example that uses mbsrtowcs() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <locale.h> 


#define SIZE 10 


int main(void) 
{ 
char mbs1[] = "abc"; 
char mbs2[] = "\x81\x41" "m" "\x81\x42"; 
const char *pmbsl = mbs1; 
const char *pmbs2 = mbs2; 
mbstate_t ssl = 0; 
mbstate_t ss2 = 0; 
wchar_t wesl [SIZE], wcs2[SIZE]; 


if (NULL == setlocale(LC_ALL, "/qsys.lib/locale.lib/ja_jp939.locale")) 


printf("setlocale failed.\n"); 

exit (EXIT_FAILURE) ; 
} 
mbsrtowcs(wcsl, &pmbs1, SIZE, 5722-SS1); 
mbsrtowcs(wcs2, &pmbs2, SIZE, &ss2); 
printf("The first wide character string is %ls.\n", wcsl); 
printf("The second wide character string is %ls.\n", wcs2); 
return 0; 


[BRK RK KKK KK EA KK ERK KEK AKER IKEA KKK AK KE IKKE IKKE IKK EA AKER EK 
The output should be similar to: 


The first wide character string is abc. 


The second wide character string is Am B.&#26 
KR KIRA KKK KKK A KKK IK KEK KKK IK KEK IKK K KAKA AKER EKERE KER | 


mbstowcs() — Convert a Multibyte String to a Wide Character String 
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Format 


#include <stdlib.h> 
size_t mbstowcs(wchar_t *pwc, const char *string, size_t n); 
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Language Level: ANSI 
Thread Safe: YES. 
Description 


The mbstowcs() function determines the length of the sequence of the multibyte 
characters pointed to by string. It then converts the multibyte character string that 
begins in the initial shift state into a wide character string, and stores the wide 
characters into the buffer that is pointed to by pwc. A maximum of n wide 
characters are written. 


The behavior of this function is affected by the LC_CTYPE category of the current 
locale. If the program is compiled with LOCALETYPE(*LOCALE), and the CCSID 
that is associated with locale is single-byte, all the multibyte characters are 
assumed to be single-byte, and are converted to wide characters like this: 0xC1 is 
converted to 0x00C1. If CCSID of the locale is a multibyte CCSID, then if the 
multibyte character is a single-byte character, it is converted as is above. If the 
multibyte character is a double-byte character, (characters between shiftout 0x0e 
and shiftin Ox0f), the double-byte characters are copied directly, stripping off the 
shiftout and shiftin characters. For example, 0x0e41710f is converted to 0x4171. 


If the program is compiled LOCALETYPE(**LOCALEUCS2), the multibyte character 
string is converted from the CCSID of the locale to UNICODE as if iconv() were 
called. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 
The mbstowcs() function returns the number of wide characters generated, not 
including any ending null wide characters. If a multibyte character that is not valid 


is encountered, the function returns (size_t)-1. 


Examples that use mbstowcs () 


Chapter 2. Library Functions 183 


/* This program is compiled with LOCALETYPE(*LOCALEUCS2) and = ~/ 
/* SYSIFCOPT (*IFSIO) */ 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
#include  <wchar.h> 
#include  <errno.h> 


#define LOCNAME —— "qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 
{ 
int length, sl = 0; 
char string[10]; 
char string2[] = "ABC"; 
wchar_t buffer[10]; 
memset(string, '\O', 10); 
string[0] = 0xC1; 
string[1] = OxOE; 
string[2] = 0x41; 
string[3] = 0x71; 
string[4] = 0x41; 
string[5] = 0x72; 
string[6] = OxOF; 
string[7] = OxC2; 
/* In this first example we will convert x/ 
/* a multibyte character when the CCSID of locale */ 
/* associated with LC_CTYPE is 37. */ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 
length = mbstowcs(buffer, string2, 10); 


/* In this case length ABC is converted to UNICODE ABC */ 
/* or 0x004100420043. Length will be 3. x/ 


printf("length = %d\n\n", length); 

/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = mbstowcs(buffer, string, 10); 


/* The buffer now has the value: */ 
/* 0x004103A103A30042 length is 4 x*/ 


printf("length = %d\n\n", length); 


} 
/* The output should look like this: 


length = 3 


length = 4 
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/* This program is compiled with LOCALETYPE(*LOCALE) and x/ 
/* SYSIFCOPT (*IFSIO) */ 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
#include <wchar.h> 
#include <errno.h> 


#define LOCNAME ——"qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 

{ 
int length, sl = 0; 
char string[10]; 
char string2[] = "ABC"; 
wchar_t buffer[10]; 
memset(string, '\O', 10); 


string[0] = O0xC1; 
string[1] = OxOE; 
string[2] = 0x41; 
string[3] = 0x71; 
string[4] = 0x41; 
string[5] = 0x72; 
string[6] = OxOF; 
string[7] = OxC2; 
/* In this first example we will convert x/ 
/* a multibyte character when the CCSID of locale x*/ 
/* associated with LC_CTYPE is 37. */ 


if (setlocale(LC_ALL, LOCNAME EN) == NULL) 
printf("setlocale failed.\n"); 


length = mbstowcs(buffer, string2, 10); 


/* In this case length ABC is converted to x/ 
/* 0x00C100C200C3. Length will be 3. */ 


printf("length = %d\n\n", length); 
/* Now lets try a multibyte example. We first must set the « 
/* locale to a multibyte locale. We choose a locale with 


/* CCSID 5026 x/ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = mbstowcs(buffer, string, 10); 


/* The buffer now has the value: */ 
/* 0x00C14171417200C2 length is 4 */ 


printf("length = %d\n\n", length); 


} 

/* The output should look like this: 
length = 3 

length = 4 


Related Information 
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mbtowc() — Convert Multibyte Character to a Wide Character 
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Format 


#include <stdlib.h> 
int mbtowc(wchar_t *pwc, const char *string, size_t n); 


Language Level: ANSI 

Thread Safe: NO. Use mbrtowc() instead. 

Description 

The mbtowc() function first determines the length of the multibyte character 
pointed to by string. It then converts the multibyte character to a wide character as 


described in mbstowcs. A maximum of n bytes are examined. 


The behavior of this function is affected by the LC_CTYPE category of the current 
locale. 


Return Value 


If string is NULL, the mbtowc() function returns: 


* Nonzero when the active locale is mixed byte. The function initializes the state 
variable. 


* 0 otherwise. 


If string is not NULL, the mbtowc() function returns: 

* 0 if string points to the null character 

* The number of bytes comprising the converted multibyte character 
* -1 if string does not point to a valid multibyte character. 


Example that uses mbtowc() 


This example uses the mblen() and mbtowc() functions to convert a multibyte 
character into a single wide character. 
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#include <stdio.h> 
#include <stdlib.h> 


#define LOCNAME "qsys.lib/mylib.1ib/ja_jp959. locale" 
/xLocale created from source JA_JP and CCSID 939 x/ 


int length, temp; 
char string [] = "\xOe\x41\x71\x0f"; 
wchar_t arr[6]; 


int main(void) 

{ 
/* initialize internal state variable «/ 
temp = mbtowc(arr, NULL, 0); 


setlocale (LC_ALL, LOCNAME) ; 

/* Set string to point to a multibyte character. */ 
length = mblen(string, MB_CUR_MAX); 

temp = mbtowc(arr,string, length) ; 

printf("wide character string: %Is",arr); 


} 


Related Information 


memchr() — Search Buffer 


Format 

#include <string.h> 

void *memchr(const void *buf, int c, size_t count); 

Language Level: ANSI 

Description 

The memchr() function searches the first count bytes of buf for the first occurrence 
of c converted to an unsigned character. The search continues until it finds c or 
examines count bytes. 


Return Value 


The memchr() function returns a pointer to the location of c in buf. It returns NULL 
if c is not within the first count bytes of buf. 


Example that uses memchr() 


This example finds the first occurrence of “x” in the string that you provide. If it is 
found, the string that starts with that character is printed. 


Chapter 2. Library Functions 187 


#include <stdio.h> 
#include <string.h> 


int main(int argc, char ** argv) 
{ 


char * result; 


if ( argc != 2 ) 
printf( "Usage: %s string\n", argv[0] ); 
else 


if ((result = (char *) memchr( argv[1], 'x', strlen(argv[1])) ) != NULL) 
printf( "The string starting with x is %s\n", result ); 


else 
printf( "The letter x cannot be found in the string\n" ); 
} 


} 


[KEKKKKEREKERKEKEREKRER Output should be similar to: **x***kkkKKKEKK 


The string starting with x is xing 
*/ 


Related Information 


memcmp() — Compare Buffers 
Format 
#include <string.h> 
int memcmp(const void *bufl, const void *buf2, size_t count); 
Language Level: ANSI 
Description 
The memcmp() function compares the first count bytes of bufl and buf2. 


Return Value 


The memcmp() function returns a value indicating the relationship between the two 
buffers as follows: 


Value Meaning 

Less than 0 bufl less than buf2 

0 bufl identical to buf2 
Greater than 0 bufl greater than buf2 


Example that uses memcmp () 
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This example compares first and second arguments passed to main() to determine 


which, if either, is greater. 


#include <stdio.h> 
#include <string.h> 


int main(int argc, char ** argv) 
{ 

int len; 

int result; 


if ( argc != 3 ) 
{ 


printf( "Usage: %s stringl string2\n", argv[0] ); 
} 
else 
{ 
/* Determine the length to be used for comparison «/ 
if (strlen( argv[1] ) < strlen( argv[2] )) 
len = strlen( argv[1] ); 
else 
len = strlen( argv[2] ); 


result = memcmp( argv[1], argv[2], len ); 


printf( "When the first %i characters are compared,\n", len ); 
if ( result == 0 ) 

printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] ); 
else if ( result < 0 ) 

printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] ); 
else 

printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] ); 


[KxkkKKKKKKKKKKEK TF the program is passed the aYQuMeNntS ****keKKKKKKEK 
KKKKKKKKEKKEKKEKRER fi rststring and secondstring, KKKKKKKKEKKER 
KKKKKKEKKKKKEKKKKRER output should be: KREKKKKKKKEKRER 


When the first 11 characters are compared, 


"firststring" is less than "secondstring" 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK AK KK ARK KKK KI KIKI KIRA KKK KER KK | 


Related Information 


memcpy() — Copy Bytes 
Format 
#include <string.h> 
void *memcpy(void *dest, const void *src, size_t count); 
Language Level: ANSI 


Description 


Chapter 2. Library Functions 


189 


The memcpy() function copies count bytes of src to dest. The behavior is undefined if 
copying takes place between objects that overlap. The memmove() function allows 
copying between objects that may overlap. 


Return Value 

The memcpy() function returns a pointer to dest. 
Example that uses memcpy () 

This example copies the contents of source to target. 


#include <string.h> 
#include <stdio.h> 


#define MAX_LEN 80 


char source[ MAX_LEN ] 
char target[ MAX_LEN ] 


"This is the source string"; 
"This is the target string"; 


int main(void) 

{ 
printf( "Before memcpy, target is \"%s\"\n", target ); 
memcpy( target, source, sizeof(source)); 
printf( "After memcpy, target becomes \"%s\"\n", target ); 


} 


[REKKKEKKRKERERKEKERERE RK Expected OUTPUTS KKK KAKKAKAKKRKKRKEKRRKEK 
Before memcpy, target is "This is the target string" 

After memcpy, target becomes "This is the source string" 

x/ 


Related Information 


memicmp - Compare Bytes 
Format 
#include <string.h> // also in <memory.h> 
int memicmp(void *bufl, void *buf2, unsigned int cnt); 
Note: The memicmp function is supported only for C++, not for C. 
Language Level: Extension 
Description 
The memicmp function compares the first cnt bytes of bufl and buf2 without regard 


to the case of letters in the two buffers. The function converts all uppercase 
characters into lowercase and then performs the comparison. 
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Return Value 


The return value of memicmp indicates the result as follows: 


Value Meaning 

Less than 0 buf1 less than buf2 

0 buf1 identical to buf2 
Greater than 0 bufl greater than buf2 


Example that uses memicmp() 


This example copies two strings that each contain a substring of 29 characters that 
are the same except for case. The example then compares the first 29 bytes without 
regard to case. 


#include <stdio.h> 
#include <string.h> 
char first[100],second[100]; 
int main(void) 
{ 
int result; 
strcpy(first, "Those Who Will Not Learn From History"); 
strcpy(second, "THOSE WHO WILL NOT LEARN FROM their mistakes"); 
printf("Comparing the first 29 characters of two strings.\n"); 
result = memicmp(first, second, 29); 
printf("The first 29 characters of String 1 are "); 
if (result < 0) 
printf("less than String 2.\n"); 
else 
if (0 == result) 
printf("equal to String 2.\n"); 
else 
printf("greater than String 2.\n"); 
return 0; 


} 


The output should be: 


Comparing the first 29 characters of two strings. 
The first 29 characters of String 1 are equal to String 2 


Related Information: 
* memchr 

* memcmp 

* memcpy 

* memmove 

* memset 

° strcmp 


* <memory.h> 
° <string.h> 


memmove() — Copy Bytes 


Format 
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#include <string.h> 
void *memmove(void *dest, const void *src, size_t count); 


Language Level: ANSI 
Description 


The memmove() function copies count bytes of src to dest. This function allows 
copying between objects that may overlap as if src is first copied into a temporary 
array. 


Return Value 
The memmove() function returns a pointer to dest. 
Example that uses memmove () 


This example copies the word "shiny” from position target + 2 to position target + 
8. 


#include <string.h> 
#include <stdio.h> 


#define SIZE 21 
char target[SIZE] = "a shiny white sphere"; 


int main( void ) 
{ 
char * p = target + 8; /* p points at the starting character 
of the word we want to replace */ 
char * source = target + 2; /* start of "shiny" */ 


printf( "Before memmove, target is \"%s\"\n", target ); 
memmove( p, source, 5 )3 
printf( "After memmove, target becomes \"%s\"\n", target ); 


} 


[RRERRRARKERARRERRRERE Expected OUtPUL:  *ek kk RRR RRR RE 


Before memmove, target is "a shiny white sphere" 
After memmove, target becomes "a shiny shiny sphere" 
*/ 


Related Information 
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#include <string.h> 
void *memset(void *dest, int c, size_t count); 


Language Level: ANSI 


Description 


The memset () function sets the first count bytes of dest to the value c. The value of c 


is converted to an unsigned character. 
Return Value 
The memset () function returns a pointer to dest. 


Example that uses memset () 


This example sets 10 bytes of the buffer to A and the next 10 bytes to B. 


#include <string.h> 
#include <stdio.h> 


#define BUF SIZE 20 


int main(void) 

{ 
char buffer[BUF_SIZE + 1]; 
char «string; 


memset (buffer, 0, sizeof(buffer)); 

string = (char *) memset(buffer,'A', 10); 
printf("\nBuffer contents: %s\n", string); 
memset (buffert10, 'B', 10); 
printf("\nBuffer contents: %s\n", buffer); 


} 


[skkRKKRRRKRKEEEEERR Output should be similar to: 
Buffer contents: AAAAAAAAAA 


Buffer contents: AAAAAAAAAABBBBBBBBBB 
*/ 


Related Information 


KKKKKKKKKKKKEKE 


mktime() — Convert Local Time 


Format 


#include <time.h> 
time_t mktime(struct tm *time); 


Language Level: ANSI 
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Thread Safe: NO. 
Description 


The mktime() function converts local time, stored as a tm structure pointed to by 
time, into a time_t structure suitable for use with other time functions. The values 
of some structure elements pointed to by time are not restricted to the ranges 
shown for gmtime(). 


The values of tm_wday and tm_yday passed to mktime()are ignored and are 
assigned their correct values on return. 


Note: 


* Calendar time is the number of seconds that have elapsed since EPOCH, 
which is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 


* On the iSeries server, the time function uses the QUTCOFFSET system 
value for calculating UTC. The QUTCOFFSET value specifies the 
difference in hours and minutes between UTC, also known as Greenwich 
mean time, and the current system time. You can override the 
QUTCOFFSET value by specifying the TZDIFF and TZNAME category of 
the current locale. 


Return Value 


The mktime() function returns the calendar time having type time_t. The value 
(time_t)(-1) is returned if the calendar time cannot be represented. 


Example that uses mkt ime() 


This example prints the day of the week that is 40 days and 16 hours from the 
current date. 


#include <stdio.h> 
#include <time.h> 


char *wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday", 
"Thursday", "Friday", "Saturday" }; 


int main(void) 

{ 
time_t tl, t3; 
struct tm *t2; 


tl = time(NULL) ; 
t2 = localtime(&t1); 
t2 -> tm_mday += 40; 
t2 -> tm_hour += 16; 
t3 = mktime(t2); 


printf("40 days and 16 hours from now, it will be a %s \n", 
wday[t2 -> tm_wday]); 
} 


[EKRKKERKEKERKEKERERE Output should be similar tO: ***#kx*kKKKKEKKK 


40 days and 16 hours from now, it will be a Sunday 
x/ 


Related Information 
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modf() — Separate Floating-Point Value 


Format 


#include <math.h> 
double modf(double x, double *intptr); 


Language Level: ANSI 
Description 


The modf() function breaks down the floating-point value x into fractional and 
integral parts. The signed fractional portion of x is returned. The integer portion is 
stored as a double value pointed to by intptr. Both the fractional and integral parts 
are given the same sign as x. 


Return Value 
The modf() function returns the signed fractional portion of x. 
Example that uses modf () 


This example breaks the floating-point number —14.876 into its fractional and 
integral components. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double x, y, d; 


Xx 
y 


-14.876; 
modf(x, &d); 


printf("x = %1f\n", x); 

printf("Integral part = %1f\n", d); 

printf("Fractional part = %1f\n", y); 
} 


[KEKRKRKREKEREKKR Output should be similar tO: ***kXKKKKKKKKKKKEK 


x = -14.876000 

Integral part = -14.000000 
Fractional part = -0.876000 
x/ 
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Related Information 


nl_langinfo() —Retrieve Locale Information 
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Format 


#include <langinfo.h> 
#include <nl_types.h> 


char *nl_langinfo(nl_item item); 


Thread Safe: NO. 


Description 


The nl_langinfo() function retrieves from the current locale the string that 
describes the requested information specified by item. 


The retrieval of the following information from the current locale is supported: 


CODESET Explanation 

D_T_FMT string for formatting date and time 

D_FMT date format string 

T_FMT time format string 

T_FMT_AMPM a.m. or p.m. time format string 

AM_STR Ante Meridian affix 

PM_STR Post Meridian affix 

DAY_1 name of the first day of the week (for example, Sunday) 
DAY_2 name of the second day of the week (for example, Monday) 
DAY_3 name of the third day of the week (for example, Tuesday) 
DAY_4 name of the fourth day of the week (for example, Wednesday) 
DAY_5 name of the fifth day of the week (for example, Thursday) 
DAY_6 name of the sixth day of the week (for example, Friday) 
DAY_7 name of the seventh day of the week (for example, Saturday) 
ABDAY_1 abbreviated name of the first day of the week 

ABDAY_2 abbreviated name of the second day of the week 

ABDAY_3 abbreviated name of the third day of the week 

ABDAY_4 abbreviated name of the fourth day of the week 

ABDAY_5 abbreviated name of the fifth day of the week 

ABDAY_6 abbreviated name of the sixth day of the week 

ABDAY_7 abbreviated name of the seventh day of the week 

MON_1 name of the first month of the year 

MON_2 name of the second month of the year 

MON_3 name of the third month of the year 

MON_4 name of the fourth month of the year 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


MON_5 name of the fifth month of the year 

MON_6 name of the sixth month of the year 

MON_7 name of the seventh month of the year 

MON_8 name of the eighth month of the year 

MON_9 name of the ninth month of the year 

MON_10 name of the tenth month of the year 

MON_11 name of the eleventh month of the year 

MON_12 name of the twelfth month of the year 

ABMON_1 abbreviated name of the first month of the year 

ABMON_2 abbreviated name of the second month of the year 

ABMON_3 abbreviated name of the third month of the year 

ABMON_4 abbreviated name of the fourth month of the year 

ABMON_5 abbreviated name of the fifth month of the year 

ABMON_6 abbreviated name of the sixth month of the year 

ABMON_7 abbreviated name of the seventh month of the year 

ABMON_8 abbreviated name of the eighth month of the year 

ABMON_9 abbreviated name of the ninth month of the year 

ABMON_10 abbreviated name of the tenth month of the year 

ABMON_11 abbreviated name of the eleventh month of the year 

ABMON_ 12 abbreviated name of the twelfth month of the year 

ERA era description segments 

ERA _D_FMT era date format string 

ERA_D_T_FMT era date and time format string 

ERA_T_FMT era time format string 

ALT_DIGITS alternative symbols for digits 

RADIXCHAR radix character 

THOUSEP separator for thousands 

YESEXPR affirmative response expression 

NOEXPR negative response expression 

YESSTR affirmative response for yes/no queries 

NOSTR negative response for yes/no queries 

CRNCYSTR currency symbol, preceded by ’—’ if the symbol should appear 
before the value, ’+’ if the symbol should appear after the value, 
or ’.” if the symbol should replace the radix character 


Returned Value 


The nl_langinfo() function returns a pointer to a null-ended string containing 
information concerning the active language or cultural area. The active language or 
cultural area is determined by the most recent setlocale() call. The array pointed 
to by the returned value is modified by subsequent calls to the function. The array 
should not be changed by the user’s program. 


If the item is not valid, the function returns a pointer to an empty string. 
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Example that uses n1_langinfo() 


This example retrieves the name of the codeset using the nl_langinfo() function. 


#include <langinfo.h> 
#include <locale.h> 
#include <nl_types.h> 
#include <stdio.h> 
int main(void) 


printf("Current codeset is %s\n", nl_langinfo(CODESET)); 
return 0; 


} 


[RK RK KER KK ERK KEK K KKK AKER K KAKA I KKK KKK KKK KKK KAKA KKK KAA KER EK 
The output should be similar to: 
Current codeset is 37 


KKK AK KKK KEKE AK KEK KKK AKER KKK AKKEAK KEI KKK KKK EKA IKEA KK EKA K KERR | 


Related Information 


perror() — Print Error Message 


Format 


#include <stdio.h> 
void perror(const char *string); 


Language Level: ANSI 

Description 

The perror() function prints an error message to stderr. If string is not NULL and 
does not point to a null character, the string pointed to by string is printed to the 
standard error stream, followed by a colon and a space. The message associated 
with the value in errno is then printed followed by a new-line character. 

To produce accurate results, you should ensure that the perror() function is called 
immediately after a library function returns with an error; otherwise, subsequent 
calls may alter the errno value. 

Return Value 


There is no return value. 


The value of errno may be set to: 
Value Meaning 


EBADDATA 
The message data is not valid. 
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EBUSY 
The record or file is in use. 


ENOENT 
The file or library cannot be found. 


EPERM 
Insufficient authorization for access. 


ENOREC 
Record not found. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Example that uses perror() 


This example tries to open a stream. If fopen() fails, the example prints a message 
and ends the program. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 
FILE «fh; 


if ((fh = fopen("mylib/myfile","r")) == NULL) 
{ 
perror("Could not open data file"); 
abort(); 
} 
} 


Related Information 


pow() — Compute Power 
Format 
#include <math.h> 
double pow(double x, double y); 
Language Level: ANSI 
Description 
The pow() function calculates the value of x to the power of y. 
Return Value 
If y is 0, the pow() function returns the value 1. If x is 0 and y is negative, the 


pow() function sets errno to EDOM and returns 0. If both x and y are 0, or if x is 
negative and y is not an integer, the pow() function sets errno to EDOM, and 
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returns 0. The errno variable may also be set to ERANGE. If an overflow results, 
the pow() function returns +HUGE_VAL for a large result or -HUGE_VAL for a 
small result. 


Example that uses pow() 
This example calculates the value of 2°. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 


double x, y, Z3 


x = 2.0; 
y = 3.0; 
z = pow(x,y)s 


printf("%1f to the power of %lf is %1f\n", x, y, 2z)3 
} 


[KEKKRKKEREKEREKERK Output should be similar tO: *****KKKKKKKKKKKK 


2.000000 to the power of 3.000000 is 8.000000 
*/ 


Related Information 


printf() — Print Formatted Characters 


Format 


#include <stdio.h> 
int printf(const char *format-string, argument-list); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The printf() function formats and prints a series of characters and values to the 
standard output stream stdout. Format specifications, beginning with a percent 
sign (%), determine the output format for any argument-list following the 
format-string. The format-string is a multibyte character string beginning and ending 
in its initial shift state. 


The format-string is read left to right. When the first format specification is found, 
the value of the first argument after the format-string is converted and output 
according to the format specification. The second format specification causes the 
second argument after the format-string to be converted and output, and so on 
through the end of the format-string. If there are more arguments than there are 
format specifications, the extra arguments are evaluated and ignored. The results 
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are undefined if there are not enough arguments for all the format specifications. 
Only 15 significant digits are guaranteed for conversions of floating point numbers. 


A format specification has the following form: 


pp —% | 


flags 


type >< 


width | .-— precision | h 


Conversions can be applied to the nth argument after the format-string in the 
argument list, rather than to the next unused argument. In this case, the conversion 
character % is replaced by the sequence %on$, where n is a decimal integer in the 
range 1 thru NL_LARGMAX, giving the position of the argument in the argument 
list. This feature provides for the definition of format strings that select arguments 
in an order appropriate to specific languages. 


Alternative format specification has the following form: 


>>—%s—arg-number$ 


type >< 


* | width | : precision | 


ss r> 


As an alternative, specific entries in the argument-list may be assigned by using 
the format specification outlined in the diagram above. This format specification 
and the previous format specification may not be mixed in the same call to 
scanf(). Otherwise, unpredictable results may occur. 


The arg-number is a positive integer constant where 1 refers to the first entry in 
the argument-list. Arg-number may not be greater than the number of entries in 
the argument-list, or else the results are undefined. Arg-number also may not be 
greater than NL_ARGMAX. 


In format strings containing the %on$ form of conversion specifications, numbered 
arguments in the argument list can be referenced from the format string as many 
times as required. 


In format strings containing the %on$ form of a conversion specification, a field 
width or precision may be indicated by the sequence *m$, where m is a decimal 
integer in the range 1 thru NL_ARGMAX giving the position in the argument list 
(after the format argument) of an integer argument containing the field width or 
precision, for example: 


printf ("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 


The format-string can contain either numbered argument specifications (that is, 
%n$ and *m$), or unnumbered argument specifications (that is, % and *), but 
normally not both. The only exception to this is that %% can be mixed with the 
%n$ form. The results of mixing numbered and unnumbered argument 
specifications in a format-string string are undefined. When numbered argument 
specifications are used, specifying the nth argument requires that all the leading 
arguments, from the first to the (n-1)th, are specified in the format string. 
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Each field of the format specification is a single character or number signifying a 
particular format option. The type character, which appears after the last optional 
format field, determines whether the associated argument is interpreted as a 
character, a string, a number, or pointer. The simplest format specification contains 
only the percent sign and a type character (for example, %s). 


The following optional fields control other aspects of the formatting: 


Field Description 


lags ustification of output and printing of signs, blanks, decimal points, octal, 
& P 8 & P 
and hexadecimal prefixes, and the semantics for wchar_t precision unit. 


width Minimum number of bytes output. 


precision 
See [able 4 on page 204. 
h, 1, ll, L 
Size of argument expected: 


h A prefix with the integer types d, i, 0, u, x, X, and n that specifies 
that the argument is short int or unsigned short int. 


1 A prefix with d, i, 0, u, x, X, and n types that specifies that the 
argument is a long int or unsigned long int. 


ll A prefix with d, i, 0, u, x, X, and n types that specifies that the 
argument is a long long int or unsigned long long int. 


L A prefix with e, E, f, g, or G types that specifies that the argument 
is long double. 


Each field of the format specification is discussed in detail below. If a percent sign 
(%) is followed by a character that has no meaning as a format field, the character 
is simply copied to stdout. For example, to print a percent sign character, use %%. 


The type characters and their meanings are given in the following table: 


Character | Argument Output Format 

d,i Integer Signed decimal integer. 

u Integer Unsigned decimal integer. 

oO Integer Unsigned octal integer. 

x Integer Unsigned hexadecimal integer, using abcdef. 

Xx Integer Unsigned hexadecimal integer, using ABCDEF. 
D(n,p) Packed decimal It has the format [—] dddd.dddd where the number of 


digits after the decimal point is equal to the precision 
of the specification. If the precision is missing, the 
default is p; if the precision is zero, and the # flag is 
not specified, no decimal point character appears. If 
the n and the p are *, an argument from the argument 
list supplies the value. n and p must precede the value 
being formatted in the argument list. At least one 
character appears before a decimal point. The value is 
rounded to the appropriate number of digits. 
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Character | Argument 


Output Format 


f 


Double 


Signed value having the form [-]dddd.dddd, where dddd 
is one or more decimal digits. The number of digits 
before the decimal point depends on the magnitude of 
the number. The number of digits after the decimal 
point is equal to the requested precision. 


Double 


Signed value having the form [-]d.dddd e[sign]ddd, 
where d is a single-decimal digit, dddd is one or more 
decimal digits, ddd is 2 or 3 decimal digits, and sign is 
+ or -. 


Double 


Identical to the e format except that E introduces the 
exponent instead of e. 


Double 


Signed value printed in f or e format. The e format is 
used only when the exponent of the value is less than 
-4 or greater than precision. Trailing zeros are 
truncated, and the decimal point appears only if one 
or more digits follow it. 


Double 


Identical to the g format except that E introduces the 
exponent (where appropriate) instead of e. 


Character (byte) 


Single character. 


String 


Characters (bytes) printed up to the first null character 
(\0) or until precision is reached." 


Pointer to integer 


Number of characters (bytes) successfully written so 
far to the stream or buffer; this value is stored in the 
integer whose address is given as the argument. 


Pointer 


Pointer converted to a sequence of printable 
characters. It can be one of the following: 


* space pointer 

* system pointer 

* invocation pointer 
* procedure pointer 
* open pointer 

* suspend pointer 

* data pointer 

* label pointer 


Ic or C 


Wide Character 


The (wchar_t) character is converted to a multibyte 
character as if by a call to wctomb(), and this character 
is printed out.” 


Is or S 


Wide Character 


The (wchar_t) characters up to the first (wchar_t) null 
character (L\0), or until precision is reached, are 
converted to multibyte characters, as if by a call to 
wcstombs(), and these characters are printed out. If 
the argument is a null string, (null) is printed.” 


Note? 


Note” 


If the program is compiled with LOCALETYPE(**LOCALEUCS2) and 
SYSIFCOPT(*IFSIO), then the wide characters are assumed to be 


UNICODE characters. 


When printing to the screen in a UNICODE environment, the wide 
characters are converted to the CCSID of the job before they are printed 


out. 
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The following list shows the format of the printed values for iSeries pointers, and 
gives a brief description of the components of the printed values. 


Space pointer: SPP:Context:Object:Offset:AG 


Context: type, subtype and name of the context 
Object: type, subtype and name of the object 
Offset: offset within the space 

AG: Activation group ID 


System pointer: SYP:Context:Object:Auth:Index:AG 


Context: type, subtype and name of the context 
Object: type, subtype and name of the object 
Auth: authority 

Index: Index associated with the pointer 

AG: Activation group ID 


Invocation pointer: IVP:Index:AG 


Index: Index associated with the pointer 
AG: Activation group ID 


Procedure pointer: PRP:Index:AG 


Index: Index associated with the pointer 
AG: Activation group ID 


Suspend pointer: SUP:Index:AG 


Index: Index associated with the pointer 
AG: Activation group ID 


Data pointer: DTP:Index:AG 


Index: Index associated with the pointer 
AG: Activation group ID 


Label pointer: LBP:Index:AG 


Index: Index associated with the pointer 
AG: Activation group ID 


NULL pointer: NULL 


The following restrictions apply to pointer printing and scanning on the iSeries 
system: 


* Ifa pointer is printed out and scanned back from the same activation group, the 
scanned back pointer will be compared equal to the pointer printed out. 


* Ifa scanf() family function scans a pointer that was printed out by a different 
activation group, the scanf() family function will set the pointer to NULL. 


See the WebSphere Development Studio: ILE C/C++ Programmer’s Guide for more 
information about using iSeries pointers. 
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The flag characters and their meanings are as follows (notice that more than one 
flag can appear in a format specification): 


Flag Meaning Default 
: Left-justify the result within the field width. Right-justify. 
+ Prefix the output value with a sign (+ or —) if the Sign appears only 
output value is of a signed type. for negative signed 
values (-—). 
blank(’ ') Prefix the output value with a blank if the output | No blank. 
value is signed and positive. The + flag overrides 
the blank flag if both appear, and a positive signed 
value will be output with a sign. 
# When used with the 0, x, or X formats, the # flag No prefix. 
prefixes any nonzero output value with 0, Ox, or OX, 
respectively. 
When used with the f, D(n,p), e, or E formats, the # | Decimal point 
flag forces the output value to contain a decimal appears only if 
point in all cases. digits follow it. 
When used with the g or G formats, the # flag Decimal point 
forces the output value to contain a decimal point appears only if 
in all cases and prevents the truncation of trailing digits follow it; 
zeros. trailing zeros are 
truncated. 
When used with the Is format, the # flag causes Precision indicates 
precision to be measured in characters, regardless of | the maximum 
the size of the character. For example, if single-byte | number of bytes to 
characters are being printed, a precision of 4 would | be output. 
result in 4 bytes being printed. If double-byte 
characters are being printed, a precision of 4 would 
result in 8 bytes being printed. 
When used with the p format, the # flag converts Pointer converted 
the pointer to hex digits. These hex digits cannot be | to a sequence of 
converted back into a pointer. printable 
characters. 
0 When used with the d, i, D(n,p) 0, u, x, X, e, E, f, g, | Space padding. No 
or G formats, the 0 flag causes leading Os to pad space padding for 
the output to the field width. The 0 flag is ignored | D(n,p). 
if precision is specified for an integer or if the — 
flag is specified. 


The # flag should not be used with c, lc, d, i, u, or s types. 


Width is a nonnegative decimal integer controlling the minimum number of 
characters printed. If the number of characters (bytes) in the output value is less 
than the specified width, blanks are added on the left or the right (depending on 
whether the - flag is specified) until the minimum width is reached. 


Width never causes a value to be truncated; if the number of characters (bytes) in 
the output value is greater than the specified width, or width is not given, all 
characters of the value are printed (subject to the precision specification). 


Chapter 2. Library Functions 205 


206 


For the ls type, width is specified in bytes. If the number of bytes in the output 
value is less than the specified width, single-byte blanks are added on the left or 
the right (depending on whether the - flag is specified) until the minimum width is 


reached. 


The width specification can be an asterisk (*), in which case an argument from the 
argument list supplies the value. The width argument must precede the value being 
formatted in the argument list. 


Precision is a nonnegative decimal integer preceded by a period, which specifies the 
number of characters to be printed or the number of decimal places. Unlike the 
width specification, the precision can cause truncation of the output value or 
rounding of a floating-point or packed decimal value. 


The precision specification can be an asterisk (*), in which case an argument from 
the argument list supplies the value. The precision argument must precede the 
value being formatted in the argument list. 


The interpretation of the precision value and the default when the precision is 


omitted depend on the type, as shown in the following table: 


Table 4. Values of Precision 


Type Meaning Default 

i Precision specifies the minimum number of If precision is 0 or 

d digits to be printed. If the number of digits in | omitted entirely, or if 

u the argument is less than precision, the output _| the period (.) appears 

fe) value is padded on the left with zeros. The without a number 

x value is not truncated when the number of following it, the 

xX digits exceeds precision. precision is set to 1. 

f Precision specifies the number of digits to be Default precision for f, e 

D(n,p) printed after the decimal point. The last digit and E is six. Default 

e printed is rounded. precision for D(n,p) is p. 

E If precision is 0 or the 
period appears without 
a number following it, 
no decimal point is 
printed. 

g Precision specifies the maximum number of All significant digits 

G significant digits printed. are printed. Default 
precision is six. 

c No effect. The character is 
printed. 

Ic No effect. The wchar_t character 
is converted and 
resulting mulitbyte 
character is printed. 

s Precision specifies the maximum number of Characters are printed 
characters to be printed. Characters in excess of | until a null character is 
precision are not printed. encountered. 

ls Precision specifies the maximum number of wchar_t characters are 
bytes to be printed. Bytes in excess of precision | converted and resulting 
are not printed; however, multibyte integrity is | multibyte characters are 
always preserved. printed. 


Return Value 
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The printf() function returns the number of bytes printed. The value of errno 
may be set to ETRUNC. 


Note: The radix character for the printf() function is locale sensitive. The radix 
character is the decimal point to be used for the #flag character of the 
format string parameter for the format types f, D(n,p), e, E, g, and G. 


Example that uses printf () 
This example prints data in a variety of formats. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 


char ch = 'h', *string = "computer"; 
int count = 234, hex = 0x10, oct = 010, dec = 10; 
double fp = 251.7366; 


wchar_t we = (wchar_t)0x0058; 
wchar_t ws[4]; 


printf ("1234567890123%n4567890123456789\n\n", &count) ; 
printf("Value of count should be 13; count = %d\n\n", count); 
printf ("%10c%5c\n", ch, ch); 

printf ("%25s\n%25.4s\n\n", string, string); 

printf ("%f Biot %e %E\n\n", fp, fp, fp, fp); 

printf ("%i %i %i\n\n", hex, oct, dec); 


} 

[KEKKRKRRKRKEKERKEKER Output Should be similar tO: *x*kKKKKKKKKKEKKK 
234 = +234 000234 EA ea 352 
12345678901234567890123456789 


Value of count should be 13; count = 13 


computer 
comp 


251.736600 251.74 2.517366e+02 2.517366E+02 
16 8 10 
HAKKAR KKK AK KIRKE KKK EIR KEE A KK AK REIKI KEKE KK KEK IKKE A KEKE AKER | 


Example that uses printf () 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 


/* This program is compiled with LOCALETYPE(*LOCALEUCS2) and */ 
/* SYSIFCOPT (*IFSIO) x/ 

/* We will assume the locale setting is the same as the CCSID of the */ 

/* job. We will also assume any files involved have a CCSID of */ 

/* 65535 (no convert). This way if printf goes to the screen or */ 

/* a file the output will be the same. */ 


int main(void) 
{ 
wchar_t we = 0x0058; /* UNICODE X */ 
wehar_t ws[4]; 
setlocale(LC_ALL, 
"/QSYS.LIB/EN_US.LOCALE"); /* a CCSID 37 locale */ 
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ws[0] = 0x0041; /* UNICODE A */ 

ws[1] = (wchar_t)0x0042; /* UNICODE B- x/ 
ws[2] = (wchar_t)0x0043; /* UNICODE C */ 
ws[3] = (wchar_t)0x0000; 


/* The output displayed is CCSID 37 */ 
printf("%lc  %1s\n\n",wc,ws); 
printf("%lc  %.21s\n\n",wc,ws); 


/* Now lets try a mixed byte CCSID example +*/ 
/* You would need a device that can handle mixed bytes to */ 
/* display this correctly. */ 


setlocale(LC_ALL, 
"/QSYS.LIB/JA_JP.LOCALE");/* a CCSID 5026 locale */ 


/* big A means an A that takes up 2 bytes on the screen’ */ 


/* It will look bigger then single byte A x/ 
ws[0] = (wchar_t)OxFF21; /* UNICODE big A */ 

ws[1] = (wchar_t)OxFF22; /* UNICODE big B- */ 

ws[2] = (wchar_t)OxFF23; /* UNICODE big C */ 

ws[3] = (wchar_t)0x0000; 

we = Oxff1l; /* UNICODE big 1 */ 


printf("%lc %1s\n\n",wc,ws) ; 


/* The output of this printf is not shown below and it */ 
/* will differ depending on the device you display it */ 
/* but if you looked at the string in hex it would look */ 
/* like this: O0E42F10F404040400E42C142C242C30F */ 
/* OE is shift out, OF is shift in, and 42F1 is the */ 
/* big 1 in CCSID 5026 x/ 


printf("%lc  %.41s\n\n",wc,ws); 


/* The output of this printf is not shown below either. */ 


/* The hex would look like: */ 
/* OE42F10F404040400E42C10F */ 
/* Since the precision is in bytes we only get 4 bytes */ 
/* of the string. */ 


printf("%lc  %#.21s\n\n",wc,ws) ; 


/* The output of this printf is not shown below either. */ 


/* The hex would look like: x/ 
/* QE42F10F404040400E42C142C20F */ 
/* The # means precision is in characters reguardless  */ 
/* of size. So we get 2 characters of the string. */ 


} 


[EKER EKRKERKERERK Output Should be similar tO: ***kKKKKKKKKKEKKK 


X ABC 


KR KKK A KKK KKK AK KKK KKK IK KKK KKK KKK KKK KKK KEK KKK KKK KKK IAEA AKER KK | 


Example that uses printf () 


#include <stdio.h> 

#include <stdlib.h> 

#include <locale.h> 

/* This program is compile LOCALETYPE(*LOCALE) and x*/ 
/* SYSIFCOPT(*IFSIO) x/ 

int main(void) 


{ 
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wchar_t we = (wchar_t)0x00C4; /* D */ 
wehar_t ws[4]; 


ws[0] = (wchar_t)0x00C1; /* A x/ 
ws[1] = (wchar_t)0x00C2; /* B x/ 
ws[2] = (wchar_t)0x00C3; /*C */ 
ws[3] = (wchar_t)0x0000; 


/* The output displayed is CCSID 37 */ 
printf("%lc %1s\n\n",wc,ws); 


/* Now lets try a mixed byte CCSID example */ 
/* You would need a device that can handle mixed bytes to */ 
/* display this correctly. */ 


setlocale(LC_ALL, 
"/QSYS.1ib/JA_JP.LOCALE"); /* a CCSID 5026 locale */ 


/* big A means an A that takes up 2 bytes on the screen” */ 


/* It will look bigger then single byte A x/ 
ws[0] = (wchar_t)0x42C1; /* big A */ 

ws[1] = (wchar_t)0x42C2; /* big B x/ 

ws[2] = (wchar_t)0x42C3; /* big C */ 

ws[3] = (wchar_t)0x0000; 

we = Ox42F1; /s big 1 +/ 


printf("%lc %1s\n\n",wc,ws); 


/* The output of this printf is not shown below and it */ 
/* will differ depending on the device you display it */ 
/* but if you looked at the string in hex it would look */ 
/* like this: OE42F10F404040400E42C142C242C30F x/ 
/* OE is shift out, OF is shift in, and 42F1 is the x*/ 
/* big 1 in CCSID 5026 */ 


printf("%lc  %.41s\n\n",wc,ws) ; 


/* The output of this printf is not shown below either. */ 


/* The hex would look like: */ 
/* QE42F10F404040400E42C10F x/ 
/* Since the precision is in bytes we only get 4 bytes */ 
/* of the string. */ 


printf("%lc  %#.21s\n\n",wc,ws) ; 


/* The output of this printf is not shown below either. */ 


/* The hex would look like: */ 
/* 0E42F10F404040400E42C142C20F */ 
/* The # means precision is in characters regardless  */ 
/* of size. So we get 2 characters of the string. */ 


} 


[KRKRKRKEREKEREKREREK Output Should be similar tO: ****xKKKKKKEKKKKK 


D ABC 


KR KKK A KKK KKK KKK KKK AK KKK KKK KKK KKK KKK AK KEIRA KKK AKER AKER KK | 


Related Information 
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putc() — putchar() — Write a Character 
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Format 


#include <stdio.h> 
int putc(int c, FILE *stream); 
int putchar(int c); 


Language Level: ANSI 


Thread Safe: NO. #undef putc or #undef putchar allows the putc or putchar 
function to be called instead of the macro version of these functions. The functions 
are thread safe. 


Description 


The putc() function converts c to unsigned char and then writes c to the output 
stream at the current position. The putchar() is equivalent to putc(c, stdout). 


The putc() function can be defined as a macro so the argument can be evaluated 
multiple times. 


The putc() and putchar() functions are not supported for files opened with 
type=record. 


Return Value 


The putc() and putchar() functions return the character written. A return value of 
EOF indicates an error. 


The value of errno may be set to: 
Value Meaning 


EPUTANDGET 
An illegal write operation occurred after a read operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Example that uses putc() 
This example writes the contents of a buffer to a data stream. In this example, the 


body of the for statement is null because the example carries out the writing 
operation in the test expression. 
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#include <stdio.h> 
#include <string.h> 


#define LENGTH 80 


int main(void) 
{ 
FILE *stream = stdout; 
int i, ch; 
char buffer[LENGTH + 1] = "Hello world"; 


/* This could be replaced by using the fwrite routine */ 
for (i = 0; 


(i < strlen(buffer)) && ((ch = putc(buffer[i], stream)) != EOF); 
++i); 

} 

[KEKAKKEKKKERKERERKERER Expected OUtPUL: RRR RRR RRR RARER RRR KK 


Hello world 
*/ 


Related Information 


putenv() — Change/Add Environment Variables 


Format 
#include <stdlib.h> 


int *putenv(const char *varname) ; 

Description 

The putenv() function sets the value of an environment variables by altering an 
existing variable or creating a new one. The varname parameter points to a string of 


the form var=x, where x is the new value for the environment variable var. 


The name cannot contain a blank or an equal ( = ) symbol. For example, 
PATH NAME=/my_lib/joe_user 


is not valid because of the blank between PATH and NAME. Similarly, 
PATH=NAME=/my_lib/joe_user 


is not valid because of the equal symbol between PATH and NAME. The system 
interprets all characters following the first equal symbol as being the value of the 
environment variable. 


Return Value 


The putenv() function returns 0 is successful. If putenv() fails then -1 is returned 
and errno is set to indicate the error. 


Chapter 2. Library Functions 211 


Example that uses putenv() 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 
{ 


char *pathvar; 


if (-1 == putenv("PATH=/:/home/userid")) { 
printf("putenv failed \n"); 
return EXIT_FAILURE; 

} 


/* getting and printing the current environment path */ 


pathvar = getenv("PATH"); 
printf("The current path is: %s\n", pathvar); 
return 0; 


} 


[BRK ARK ER KK EA KK ERK KEK KEK KKK AK KEK KK EAR KEKKKE KAKA IKEA AKER 


The output should be: 


The current path is: /:/home/userid 


Related Information 


puts() — Write a String 
Format 
#include <stdio.h> 
int puts(const char *string); 
Language Level: ANSI 
Thread Safe: YES 
Description 
The puts() function writes the given string to the standard output stream stdout; 
it also appends a new-line character to the output. The ending null character is not 
written. 


Return Value 


The puts() function returns EOF if an error occurs. A nonnegative return value 
indicates that no error has occurred. 


Example that uses puts () 


This example writes Hello World to stdout. 


212 = ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
int main(void) 
{ 


if ( puts("Hello World") == EOF ) 
printf( "Error in puts\n" ); 
} 


[RRRRRERERERARREREREERERE EXpected OULPUL: etree eR 


Hello World 
x/ 


Related Information 


putwc() — Write Wide Character 


Format 


#include <stdio.h> 
#include <wchar.h> 
wint_t putwc(wint_t wc, FILE *stream); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The putwc() function converts the wide character we to a multibyte character, and 
writes it to the stream at the current position. It also advances the file position 
indicator for the stream appropriately. The putwc() function is equivalent to the 
fputwc() function except that some platforms implement putwc() as a macro. 
Therefore, for portability, the stream argument to putwc() should not be an 
expression with side effects. 


The behavior of the putwc() function is affected by the LC_CTYPE category of the 
current locale. Using a non-wide-character function with the putwc() function on 
the same stream results in undefined behavior. After calling the putwc() function, 
flush the buffer or reposition the stream pointer before calling a write function for 
the stream, unless EOF has been reached. After a write operation on the stream, 
flush the buffer or reposition the stream pointer before calling the putwc() 
function. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The putwc() function returns the wide character written. If a write error occurs, it 
sets the error indicator for the stream and returns WEOF. If an encoding error 
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occurs when a wide character is converted to a multibyte character, the putwc() 
function sets errno to EILSEQ and returns WEOF. 


Example that uses putwc() 


The following example uses the putwc() function to convert the wide characters in 
wes to multibyte characters and write them to the file putwc.out. 


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 


int main(void) 

{ 
FILE «stream; 
wchar_t *wcs = L"A character string."; 
int iy 


if (NULL == (stream = fopen("putwc.out", "w"))) { 
printf("Unable to open: \"putwc.out\".\n"); 


exit(1); 
} 
for (i = 0; wes[i] != L'\O'; it+) { 
errno = 0; 
if (WEOF == putwc(wces[i], stream)) { 
printf("Unable to putwc() the wide character. \n" 
"wes[%d] = Ox%1x\n", i, wes[i]); 
if (EILSEQ == errno) 
printf("An invalid wide character was encountered.\n"); 
exit(1); 
} 
} 
fclose(stream) ; 
return 0; 


[BRK R KKK KK IK KKK A KKK KKK IKEA KKK IKKE KK KER AK EKK KKK AKER KK AAR 
The output file putwc.out should contain : 


A character string. 


KKK KK KKK KK KKK KKK KKK KKK KKK KKK KEIR KKK KKK KKK AK KIARA KER KER | 


} 


Related Information 


putwchar() — Write Wide Character to stdout 


Format 
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#include <wchar.h> 
wint_t putwchar(wint_t wc); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The putwchar() function converts the wide character we to a multibyte character 
and writes it to stdout. A call to the putwchar() function is equivalent to putwc(wc, 
stdout). 


The behavior of this function is affected by the LC_CTYPE category of the current 
locale. Using a non-wide-character function with the putwchar() function on the 
same stream results in undefined behavior. After calling the putwchar() function, 
flush the buffer or reposition the stream pointer before calling a write function for 
the stream, unless EOF has been reached. After a write operation on the stream, 
flush the buffer or reposition the stream pointer before calling the putwchar() 
function. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 

Return Value 

The putwchar() function returns the wide character written. If a write error occurs, 

the putwchar() function sets the error indicator for the stream and returns WEOF. 

If an encoding error occurs when a wide character is converted to a multibyte 

character, the putwchar() function sets errno to EILSEQ and returns WEOF. 


Example that uses putwchar() 


This example uses the putwchar() function to write the string in wes. 
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#include <stdio.h> 
#include <wchar.h> 
#include <errno.h> 
#include <stdlib.h> 


int main(void) 

{ 
wchar_t *wcs = L"A character string."; 
int ae 


for (i = 0; wes[i] != L'\O'; it+) { 
errno = 0; 
if (WEOF == putwchar(wcs[i])) { 
printf("Unable to putwchar() the wide character.\n"); 
printf("wes[%d] = 0x%1x\n", i, wes[i]); 
if (EILSEQ == errno) 
printf("An invalid wide character was encountered.\n"); 
exit (EXIT_FAILURE) ; 
} 
} 
return 0; 
[RRR KKK KKK KKK KKK KKK IKEA KK AK KEI KKK AK KAKA KKK KAKA KKK 
The output should be similar to : 


A character string. 


KKK AK KKK KK KKK KEK KKK IKK KKK KAKA KK EAR KAKA KEK AREA KERR | 


} 


Related Information 


qsort() — Sort Array 
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Format 
#include <stdlib.h> 
void qsort(void *base, size_t num, size_t width, 
int(*compare) (const void «key, const void *element)); 


Language Level: ANSI 
Description 


The qsort() function sorts an array of num elements, each of width bytes in size. 
The base pointer is a pointer to the array to be sorted. The qsort() function 
overwrites this array with the sorted elements. 


The compare argument is a pointer to a function you must supply that takes a 
pointer to the key argument and to an array element, in that order. The qsort() 
function calls this function one or more times during the search. The function must 
compare the key and the element and return one of the following values: 


Value Meaning 
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Less than 0 key less than element 


0 key equal to element 


Greater than 0 key greater than element 


Value Meaning 


Less than 0 
key less than element 


0 key equal to element 


Greater than 0 
key greater than element 


The sorted array elements are stored in ascending order, as defined by your 
compare function. You can sort in reverse order by reversing the sense of “greater 
than” and “less than” in compare. The order of the elements is unspecified when 
two elements compare equally. 

Return Value 

There is no return value. 


Example that uses qsort() 


This example sorts the arguments (argv) in ascending lexical sequence, using the 
comparison function compare() supplied in the example. 
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#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 


/* Declaration of compare() as a function */ 
int compare(const void *, const void *); 


int main (int argc, char «argv[ ]) 
{ 
int is; 
argvt+ts 
argc--; 
qsort((char *)argv, argc, sizeof(char *), compare); 
for (i = 0; i < argc; ++i) 
printf("%s\n", argv[i]); 
return 0; 


} 


int compare (const void *argl, const void *arg2) 
{ 
/* Compare all of both strings */ 
return(strcemp(*(char **)argl, *(char **)arg2)); 


} 


/xxxxxxxxxxx Tf the program is passed the arguments: ***x*xxxxx#* 
xxxxxeke 'Does' 'this' 'really' ‘sort! 'the' 'arguments' ‘correctly? !**** 
KKKKKKKKKKKKEKERK then the expected output [Sf KRKKKKKKKEKKEKKEKERE 


arguments 
correctly? 
really 
sort 

the 

this 

Does 

x/ 


Related Information 


QXXCHGDA() —Change Data Area 


Format 
#include <xxdtaa.h> 


void QXXCHGDA(_DTAA_NAME_T dtaname, short int offset, short int len, 
char *dtaptr); 


Language Level: ILE C Extension 
Description 


The QXXCHGDA() function allows you to change the data area specified by dtaname, 
starting at position offset, with the data in the user buffer pointed to by dtaptr of 
length Jen. The structure dtaname contains the names of the data area and the 
library that contains the data area. The values that can be specified for the data 
area name are: 


*LDA Specifies that the contents of the local data area are to be changed. The 
library name dtaa_lib must be blank. 
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*GDA Specifies that the contents of the group data area are to be changed. The 
library name dtaa_lib must be blank. 


data-area-name 
Specifies that the contents of the data area created using the Create Data 
Area (CRTDTAARA) CL command are to be changed. The library name 
dtaa_lib must be either *LIBL, *CURLIB, or the name of the library where 
the data area (data-area-name) is located. The data area is locked while it is 
being changed. 


QXXCHGDA can only be used to change character data. 
Example that uses QXXCHGDA() 


#include <stdio.h> 
#include <xxdtaa.h> 


#define START 1 
#define LENGTH 8 


int main(void) 
{ 
char newdata[LENGTH] = "new data"; 


/* The local data area will be changed */ 
_DTAA_NAME_T dtaname = {"*LDA Ot "hs 
/* Use function to change the local data area. */ 


QXXCHGDA (dtaname, START, LENGTH, newdata) ; 
/* The first 8 characters in the local data area */ 
/* are: new data */ 


} 


Related Information 


QXXDTOP() — Convert Double to Packed Decimal 


Format 


#include <xxcvt.h> 
void QXXDTOP(unsigned char *pptr, int digits, int fraction, 
double value); 


Language Level: ILE C Extension 

Description 

The QXXDTOP function converts the double value specified in value to a packed 
decimal number with digits total digits, and fraction fractional digits. The result is 


stored in the array pointed to by zptr. 


Example that uses QXXDTOP() 
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#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 
unsigned char pptr[10]; 
int digits = 8, fraction = 6; 
double value = 3.141593; 


QXXDTOP(pptr, digits, fraction, value); 
} 


Related Information 


QXXDTOZ() —Convert Double to Zoned Decimal 
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Format 


#include <xxcvt.h> 
void QXXDTOZ(unsigned char *zptr, int digits, int fraction, 
double value); 


Language Level: ILE C Extension 
Description 


The QXXDTOZ function converts the double value specified in value to a zoned 
decimal number with digits total digits, and fraction fractional digits. The result is 
stored in the array pointed to by zptr. 


Example that uses QXXDTOZ() 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 

{ 
unsigned char zptr[10]; 
int digits = 8, fraction = 6; 
double value = 3.141593; 


QXXDTOZ(zptr, digits, fraction, value); 
} /* Zoned value is : 03141593 */ 


Related Information 
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QXXITOP() —Convert Integer to Packed Decimal 


Format 


#include <xxcvt.h> 
void QXXITOP(unsigned char *pptr, int digits, int fraction, 
int value); 


Language Level: ILE C Extension 
Description 


The QXXITOP function converts the integer specified in value to a packed decimal 
number with digits total digits, and fraction fractional digits. The result is stored in 
the array pointed to by pptr. 


Example that uses QXXITOP() 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 
unsigned char pptr[10]; 
int digits = 3, fraction = 0; 


int value = 116; 


QXXITOP(pptr, digits, fraction, value); 
} 


Related Information 


QXXITOZ() —Convert Integer to Zoned Decimal 


Format 

#include <xxcvt.h> 

void QXXITOZ(unsigned char *zptr, int digits, int fraction, int value); 
Language Level: ILE C Extension 

Description 

The QXXITOZ function converts the integer specified in value to a zoned decimal 


number with digits total digits, and fraction fractional digits. The result is stored in 
the array pointed to by zptr. 
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Example that uses QXXITOZ() 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 

{ 
unsigned char zptr[10]; 
int digits = 9, fraction = 0; 
int value = 111115; 


QXXITOZ(zptr, digits, fraction, value); 
/* Zoned value is : 000111115 */ 


} 


Related Information 


QXXPTOD() —Convert Packed Decimal to Double 


Format 


#include <xxcvt.h> 
double QXXPTOD(unsigned char *pptr, int digits, int fraction); 


Language Level: ILE C Extension 

Description 

The QXXPTOD function converts a packed decimal number to a double. 
Example that uses QXXPTOD() 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 
{ 
unsigned char pptr[10]; 
int digits = 8, fraction = 6; 
double value = 6.123456, result; 
/* First convert an integer to a packed decimal,*/ 
QXXDTOP(pptr, digits, fraction, value); 


/* then convert it back to a double. */ 
result = QXXPTOD(pptr, digits, fraction); 
/* result = 6.123456 */ 


} 


Related Information 
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QXXPTOI() —Convert Packed Decimal to Integer 


Format 


#include <xxcvt.h> 
int QXXPTOI(unsigned char *pptr, int digits, int fraction); 


Language Level: ILE C Extension 

Description 

The QXXPTOI function converts a packed decimal number to an integer. 
Example that uses QXXPTOI () 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 
{ 
unsigned char pptr[10]; 
int digits = 3, fraction = 0, value = 104, result; 
/* First convert an integer to a packed decimal,*/ 
QXXITOP(pptr, digits, fraction, value); 


/* then convert it back to an integer. */ 
result = QXXPTOI(pptr, digits, fraction); 
/* result = 104 */ 


} 


Related Information 


QXXRTVDA() —Retrieve Data Area 


Format 
#include <xxdtaa.h> 


void QXXRTVDA(_DTAA_NAME_T dtaname, short int offset, 
short int len, char *dtaptr); 


Language Level: ILE C Extension 
Description 


The following typedef definition is included in the <xxdtaa.h> header file. The 
character arrays are not null-ended strings so they must be blank filled. 
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typedef struct _DTAA_NAME_T { 

char dtaa_name[10]; /* name of data area */ 

char dtaa_lib[10]; /* library that contains data area */ 
}_DTAA_NAME_T; 


The QXXRTVDA function retrieves a copy of the data area specified by dtaname 
starting at position offset with a length of len. The structure dtaname contains the 
names of the data area and the library that contains the data area. The values that 
can be specified for the data area name are: 


*LDA The contents of the local data area are to be retrieved. The library name 
dtaa_lib must be blank. 


*GDA The contents of the group data area are to be retrieved. The library name 
dtaa_lib must be blank. 


*PDA Specifies that the contents of the program initialization parameters (PIP) 
data area are to be retrieved. The PIP data area is created for each 
pre-started job and is a character area up to 2000 characters in length. You 
cannot retrieve the PIP data area until you have acquired the requester. 
The library name dtaa_lib must be blank. 


data-area-name 
Specifies that the contents of the data area created using the Create Data 
Area (CRTDTAARA) CL command are to be retrieved. The library name 
dtaa_lib must be either *LIBL, *CURLIB, or the name of the library where 
the data area (data-area-name) is located. The data area is locked while the 
data is being retrieved. 


The parameter dtaptr is a pointer to the storage that receives the retrieved copy of 
the data area. Only character data can be retrieved using QXXRTVDA. 


Example that uses QXXRTVDA() 


#include <stdio.h> 
#include <xxdtaa.h> 


#define DATA_AREA_LENGTH 30 
#define START 6 
#define LENGTH 7 


int main(void) 
{ 
char uda_area[DATA_AREA_ LENGTH] ; 


/* Retrieve data from user-defined data area currently in MYLIB */ 
_DTAA_NAME_T dtaname = {"USRDDA ", "MYLIB a 


/* Use the function to retrieve some data into uda_area. */ 
QXXRTVDA(dtaname, START, LENGTH, uda_area) ; 


/* Print the contents of the retrieved subset. */ 
printf("uda_area contains %7.7s\n",uda_area) ; 


} 


Related Information 


QXXZTOD() —Convert Zoned Decimal to Double 


Format 
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#include <xxcvt.h> 
double QXXZTOD(unsigned char *zptr, int digits, int fraction); 


Language Level: ILE C Extension 
Description 


The OXXZTOD function converts to a double, the zoned decimal number (with 
digits total digits, and fraction fractional digits) pointed to by zptr. The resulting 
double value is returned. 


Example that uses QXXZTOD() 


#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 

{ 
unsigned char zptr[] = "06123456"; 
int digits = 8, fraction = 6; 
double result; 


result = QXXZTOD(zptr, digits, fraction); 
/* result = 6.123456 */ 
} 


Related Information 


QXXZTOI() —Convert Zoned Decimal to Integer 


Format 

#include <xxcvt.h> 

int QXXZTOI(unsigned char *zptr, int digits, int fraction); 

Language Level: ILE C Extension 

Description 

The QXXZTOI function converts to an integer, the zoned decimal number (with 
digits total digits, and fraction fractional digits) pointed to by zptr. The resulting 


integer is returned. 


Example that uses QXXZTOI() 
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#include <xxcvt.h> 
#include <stdio.h> 


int main(void) 


unsigned char zptr[] = "000111115"; 
int digits = 9, fraction = 0, result; 


result = QXXZTOI(zptr, digits, fraction); 
/* result = 111115 */ 


} 


Related Information 


raise() — Send Signal 


Format 


#include <signal.h> 
int raise(int sig); 


Language Level: ANSI 
Description 


The raise() functions sends the signal sig to the running program.If compiled 

with SYSIFCOPT(*ASYNCSIGNAL) on the compilation command, this function 
uses asynchronous signals. The asynchronous version of this function throws a 
signal to the process or thread. 


Return Value 
The raise() functions returns 0 if successful, nonzero if unsuccessful. 
Example that uses raise() 


This example establishes a signal handler called sig_hand for the signal SIGUSR1. 
The signal handler is called whenever the SIGUSR1 signal is raised and will ignore 
the first nine occurrences of the signal. On the tenth raised signal, it exits the 
program with an error code of 10. Note that the signal handler must be 
reestablished each time it is called. 


#include <signal.h> 
#include <stdio.h> 


void sig hand(int); /* declaration of sig_hand() as a function */ 
int main(void) 
signal (SIGUSR1, sig_hand); /* set up handler for SIGUSR1 */ 


raise(SIGUSR1); /* signal SIGUSR1 is raised */ 


226 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


/* sig_hand() is called */ 
} 


void sig_hand(int sig) 
{ 


static int count = 0; /* initialized only once */ 


count++; 
if (count == 10) /* ignore the first 9 occurrences of this signal */ 
exit(10); 
else 
signal(SIGUSR1, sig_hand); /* set up the handler again */ 
} 


/* This is a program fragment and not a complete program */ 


Related Information 


° Signal pid in the iSeries Information Center. 


° [POSIX thread API concepts in the iSeries Information Center. 


rand(), rand_r() — Generate Random Number 


Format 


#include <stdlib.h> 
int rand(void); 
int rand_r(unsigned int *seed); 


Language Level: ANSI 

Thread Safe: rand() is not thread safe, but rand_r() is. 

Description 

The rand() function generates a pseudo-random integer in the range 0 to 
RAND_MAX (macro defined in <stdlib.h>). Use TERSTUTTOW TE before calling 
rand() to set a starting point for the random number generator. If you do not call 
the srand() function first, the default seed is 1. 

Note: The rand_r() function is the restartable version of rand(). 

Return Value 

The rand() function returns a pseudo-random number. 

Example that uses rand() 


This example prints the first 10 random numbers generated. 
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#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
int x3 
for (x = 1; x <= 10; xt+) 


printf("iteration %d, rand=%d\n", x, rand()); 


} 


[KEKRKKKRKEKERKEKERERE RK Output should be similar to: «*******kkKEK 


iteration 1, rand=16838 
iteration 2, rand=5758 
iteration 3, rand=10113 
iteration 4, rand=17515 
iteration 5, rand=31051 
iteration 6, rand=5627 
iteration 7, rand=23010 
iteration 8, rand=7419 


iteration 9, rand=16212 
iteration 10, rand=4086 
x/ 


Related Information 


_Racquire() —Acquire a Program Device 
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Format 


#include <recio.h> 
int Racquire(_RFILE *fp, char *dev); 


Language Level: ILE C Extension 

Thread Safe: NO. 

Description 

The _Racquire() function acquires the program device specified by the dev 
parameter and associates it with the file specified by fp. The dev parameter is a 
null-ended C string. The program device name must be specified in uppercase. The 
program device must be defined to the file. This function is valid for display and 
ICF files. 

Return Value 

The Racquire() function returns 1 if it is successful or zero if it is unsuccessful. 


The value of errno may be set to ELOERROR (a non-recoverable I/O error 
occurred) or EIORECERR (a recoverable I/O error occurred). 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses _Racquire() 
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#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 


int main(void) 

{ 
_RFILE «fp; 
“RIOFB_T *rfb; 


/* Open the device file. */ 
if (( fp = _Ropen ( "MYLIB/T1677RD2", "ar+" )) == NULL ) 
{ 

printf ( "Could not open file\n" ); 

exit (1); 


_Racquire ( fp,"DEVICE1" ); /* Acquire another program device. */ 
/* Replace with actual device name.*/ 


_Rformat ( fp,"FORMAT1" ); /* Set the record format for the «/ 

/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 
/* Do some processing... */ 


_Rclose ( fp ); 
} 


Related Information 


_Rclose() —Close a File 


Format 
#include <recio.h> 


int _Rclose(_RFILE *fp); 

Language Level: ILE C Extension 

Description 

The _Rclose() function closes the file specified by fp. Before this file is closed, all 
buffers associated with it are flushed and all buffers reserved for it are released. 
The file is closed even if an exception occurs. The _Rclose() function applies to all 


types of files. 


Note: Closing a file more than once in a multi-threaded environment will cause 
undefined behavior. 


Return Value 
The _Rclose() function returns zero if the file is closed successfully, or EOF if the 


close operation failed or the file was already closed. The file is closed even if an 
exception occurs, and zero is returned. 
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The value of errno may be set to: 


Value Meaning 

ENOTOPEN The file is not open. 

EIOERROR A non-recoverable I/O error occurred. 
EIORECERR A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455) for errno settings. 


Example that uses _Rclose() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 
int main(void) 


_RFILE *fps 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 


{ 


printf ( "Open failed\n" ); 


exit (1); 
} 
else 
/* Do some processing */; 


_Rclose ( fp ); 
} 


Related Information 


_Rceommit() —Commit Current Record 


Format 


#include <recio.h> 
int _Rcommit(char *cmtid); 


Language Level: ILE C Extension 


Thread Safe: NO. 


Description 


The _Rcommit() function completes the current transaction for the job that calls it 
and establishes a new commitment boundary. All changes made since the last 
commitment boundary are made permanent. Any file or resource that is open 
under commitment control in the job is affected. 


The cmtid parameter is a null-ended C string used to identify the group of changes 
associated with a commitment boundary. It cannot be longer than 4000 bytes. 


The _Rcommit() function applies to database and DDM files. 
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Return Value 


The _Rcommit() function returns 1 if the operation is successful or zero if the 
operation is unsuccessful. The value of errno may be set to EIOERROR (a 
non-recoverable I/O error occurred) or EIORECERR (a recoverable I/O error 
occurred). 


See [able 12 on page 451] and Hable 14 on page 455 for errno settings. 


Example that uses Rcommit() 


#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 
#include <string.h> 


int main(void) 


{ 


} 


char buf [40]; 
int re = 1; 
_RFILE *purf 

_RFILE «dailyf; 


/* Open purchase display file and daily transaction file */ 
if ( ( purf = _Ropen ( "MYLIB/T1677RD3", "“art+,indicators=y" )) == NULL ) 
{ 
printf ( "Display file did not open.\n" ); 
exit (1); 
} 


if ( ( dailyf = _Ropen ( "MYLIB/T1677RDA", "“wr,commit=y") ) == NULL ) 
{ 

printf ( "Daily transaction file did not open.\n" ); 

exit (2 )3 
} 


/* Select purchase record format */ 
_Rformat ( purf, "PURCHASE" ); 


/* Invite user to enter a purchase transaction. */ 
/* The _Rwrite function writes the purchase display. */ 
_Rwrite ( purf, "", 0); 

_Rreadn ( purf, buf, sizeof(buf), DFT ); 


/* Update daily transaction file x/ 
rc = (( _Rwrite ( dailyf, buf, sizeof(buf) ))->num_bytes ); 
/* If the databases were updated, then commit the transaction. */ 
/* Otherwise, rollback the transaction and indicate to the */ 
/* user that an error has occurred and end the application. x/ 
if (rc ) 

{ 

_Rcommit ( "Transaction complete" ); 

} 

else 


{ 
_Rrollbck ( ); 
_Rformat ( purf, "ERROR" ); 


} 


_Rclose ( purf ); 
_Rclose ( dailyf ); 


Related Information 
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_Rdelete() —Delete a Record 


Format 


#include <recio.h> 
_RIOFB_T * Rdelete(_RFILE *fp); 


Language Level: ILE C Extension 
Description 


The _Rdelete() function deletes the record that is currently locked for update in 
the file specified by fp. After the delete operation, the record is not locked. The file 
must be open for update. 


A record is locked for update by reading or locating to it unless _ NO_LOCK is 

specified on the read or locate option. If the _ NO_POSITION option is specified 
on the locate operation that locked the record, the record deleted may not be the 
record that the file is currently positioned to. 


This function is valid for database and DDM files. 
Return Value 


The _Rdelete() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the operation is successful, the num_bytes field contains 1. If the 
operation is unsuccessful, the num_bytes field contains zero. 

The value of errno may be set to: 

Value Meaning 


ENOTDLT 
The file is not open for delete operations. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses _Rdelete() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE «fp; 
_XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
} 


/* Get the library and file names of the file opened. x/ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the first record. */ 
_Rreadf ( fp, NULL, 20, _ DFT ); 

printf ( "First record: %10.10s\n", *(fp->in_buf) ); 

/* Delete the first record. */ 
_Rdelete ( fp ); 


_Rclose ( fp ); 
} 


Related Information 


_Rdevatr() —Get Device Attributes 


Format 


#include <recio.h> 
#include <xxfdbk.h> 
_XXDEV_ATR_T *_Rdevatr(_RFILE *fp, char *dev); 


Language Level: ILE C Extension 
Thread Safe: NO. 
Description 


The _Rdevatr() function returns a pointer to a copy of the device attributes 
feedback area for the file pointed to by fp, and the device specified by dev. 


The dev parameter is a null-ended C string. The device name must be specified in 
uppercase. 


The _Rdevatr() function is valid for display and ICF files. 
Return Value 


The Rdevatr() function returns NULL if an error occurs. 
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See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rdevatr() 


#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 


int main(int argc, char ** argv) 


_RFILE *fp; /* File pointer x/ 
_RIOFB_T *rfb; /*Pointer to the file's feedback structure x/ 
_XXIOFB_T *iofb; /* Pointer to the file's feedback area x/ 
_XXDEV_ATR_T *dv_atr; /* Pointer to a copy of the file's device */ 

/* attributes feedback area */ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", “ar+" )) == NULL ) 
{ 

printf ( "Could not open file\n" ); 

exit (1); 
} 


dv_atr = Rdevatr (fp, argv[1]); 
if (dv_atr == NULL) 
printf("Error occurred getting device attributes for %s.\n", 
argv[1]); 


_Rclose ( fp ); 
} 


Related Information 


realloc() — Change Reserved Storage Block Size 


Format 

#include <stdlib.h> 

void *realloc(void *ptr, size_t size); 

Language Level: ANSI 

Thread Safe: YES 

Description 

The realloc() function changes the size of a previously reserved storage block. 
The ptr argument points to the beginning of the block. The size argument gives the 
new size of the block, in bytes. The contents of the block are unchanged up to the 


shorter of the new and old sizes. 


If the ptr is NULL, realloc() reserves a block of storage of size bytes. It does not 
necessarily give all bits of each element an initial value of 0. 


If size is 0 and the ptr is not NULL, realloc()frees the storage allocated to ptr and 
returns NULL 


Return Value 
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The realloc() function returns a pointer to the reallocated storage block. The 
storage location of the block may be moved by the realloc() function. Thus, the 
ptr argument to the realloc () function is not necessarily the same as the return 
value. 


If size is 0, the realloc() function returns NULL. If there is not enough storage to 
expand the block to the given size, the original block is unchanged and the 
realloc() function returns NULL. 


The storage to which the return value points is aligned for storage of any type of 
object. 


Note: By default, the ILE C memory management functions malloc(), calloc() 
and realloc() obtain storage from the ILE Cfast heap, which initially is 
64944 bytes in size. This can be increased up to about 16 megabytes by 
changing the value of the -HEAP_SIZE macro (defined in the <stdio.h> 
include file). 


To change the size of the fast heap, you must do so before using malloc(), 
calloc() or realloc() in your program. 


The use of the fast heap can be bypassed by setting the [HEAP_SIZE macro 
to the value of _NO DEFAULT HEAP, also defined in the <stdlib.h> include 

d age 3 for a description of <stdlib.h>. 
Storage allocated from ‘he rae heap by real loc() cannot be freed or 
reallocated with the ILE bindable APIs CEEFRST and CEECZST. Storage 
initially allocated with the ILE bindable API CEEGTST can be reallocated 
with the realloc() function. 


To use Teraspace storage instead of heap storage without changing the C source 
code, specify the TERASPACE(*YES *TSIFC) parameter on the CRTCMOD compiler 
command. This maps the realloc() library function to C_TS_realloc(), its 
Teraspace storage counterpart. The maximum amount of Teraspace storage that can 
be allocated by each call to _C_TS_realloc() is 2GB - 240, or 214743408 bytes. For 
additional information about Teraspace, see the ILE Concepts manual. 


Example that uses real 1oc() 
This example allocates storage for the prompted size of array and then uses 


realloc() to reallocate the block to hold the new size of the array. The contents of 
the array are printed after each allocation. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


long * array; /* start of the array */ 

long * ptr; /* pointer to array */ 

int is /* index variable */ 

int numl, num2; /* number of entries of the array */ 

void print_array( long *ptr_array, int size); 

printf( "Enter the size of the array\n" ); 

scanf( "%i", &numl); 

/* allocate numl entries using malloc() */ 

if ( (array = (long *) malloc( numl * sizeof( long ))) != NULL ) 
{ 


for ( ptr = array, i = 0; i < numl ; ++i ) /* assign values */ 
*«ptrtt+ = 7; 

print_array( array, numl ); 

printf("\n"); 


else { /* malloc error */ 
perror( "Out of storage" ); 
abort(); 
} 
/* Change the size of the array ... */ 
printf( "Enter the size of the new array\n" ); 
scanf( "%i", &num2); 
if ( (array = (long *) realloc( array, num2* sizeof( long ))) != NULL ) 
{ 
for ( ptr = array + numl, i = numl; i <= num2; ++i ) 
xptrt++ = i + 2000; /* assign values to new elements */ 
print_array( array, num2 ); 


else { /* realloc error */ 
perror( "Out of storage" ); 
abort(); 
} 
} 


void print_array( long * ptr_array, int size ) 
{ 
int i; 
long * index = ptr_array; 
printf("The array of size %d is:\n", size); 
for (i = 0; i < size; ++i ) /* print the array out */ 
printf( "  array[ %i ] = %li\n", i, ptr_array[i] ); 
} 


/*xxxx If the initial value entered is 2 and the second value entered 
is 4, then the expected output is: 
Enter the size of the array 
The array of size 2 is: 
arrayl 0 ] = 0 
array[ 1] = 1 
Enter the size of the new array 
The array of size 4 is: 


array[ 0 ] = 0 

array[ 1] = 1 

array[ 2 ] = 2002 

array[ 3 ] = 2003 */ 


Related Information 
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regcomp() — Compile Regular Expression 
Format 
#include <regex.h> 
int regcomp(regex_t *preg, const char *pattern, int cflags); 
Language Level: XPG4 
Thread Safe: NO. 


Description 


The regcomp() function compiles the source regular expression pointed to by 
pattern into an executable version and stores it in the location pointed to by preg. 
You can then use the regexec()function to compare the regular expression to other 
strings. 


The cflags flag defines the attributes of the compilation process: 


errcode Description String 
REG_EXTENDED Support extended regular expressions. 
REG_NEWLINE Treat new-line character as a special 


end-of-line character; it then establishes the 
line boundaries matched by the ] and $ 
patterns, and can only be matched within a 
string explicitly using \n. (If you omit this 
flag, the new-line character is treated like 
any other character.) 


REG_ICASE Ignore case in match. 


REG_NOSUB Ignore the number of subexpressions 
specified in pattern. When you compare a 
string to the compiled pattern (using 
regexec()), the string must match the entire 
pattern. The regexec() function then returns 
a value that indicates only if a match was 
found; it does not indicate at what point in 
the string the match begins, or what the 
matching string is. 


Regular expressions are a context-independent syntax that can represent a wide 
variety of character sets and character set orderings, which can be interpreted 
differently depending on the current locale. The functions regcomp(), regerror(), 
regexec(), and regfree() use regular expressions in a similar way to the UNIX® 
awk, ed, grep, and egrep commands. 


Note: This function is accessible only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 
If the regcomp() function is successful, it returns 0. Otherwise, it returns an error 


code that you can use in a call to the regerror() function, and the content of preg 
is undefined. 
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Example that uses regcomp () 


#include <regex.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 
regex_t preg; 
char «string = "a very simple simple simple string"; 
char xpattern = "\\(sim[a-z]le\\) \\1"; 
int res 
size_t nmatch = 2; 


regmatch_t pmatch[2]; 


if (0 != (rc = regcomp(&preg, pattern, 0))) { 
printf("regcomp() failed, returning nonzero (%d)\n", rc); 
exit (EXIT_FAILURE) ; 

} 


if (0 != (rc = regexec(&preg, string, nmatch, pmatch, 0))) { 
printf("Failed to match '%s' with '%s',returning %d.\n", 
string, pattern, rc); 


else { 
printf("With the whole expression, " 
"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[0].rm_eo - pmatch[0].rm_so, &string[pmatch[0].rm_so], 
pmatch[0].rm_so, pmatch[0].rm_eo - 1); 
printf("With the sub-expression, "; 
"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[1].rm_eo - pmatch[1].rm_so, "string[pmatch[1].rm_so], 
pmatch[1].rm_so, pmatch[1].rm_eo - 1); 
} 
regfree(&preg) ; 
return 0; 


[BRK AK KKK KK RAK KKK KKK KKK AKER AK KEK KEIR KKK KEK KK KIBAKI KKK A KKK A KERRIER EK 
The output should be similar to : 


With the whole expression, a matched substring "simple simple" is found 
at position 7 to 19. 

With the sub-expression, a matched substring "simple" is found 

at position 7 to 12. 


KKK KA KKK KKK EA KKK KKK KK KEK IKEA KK AK KAKA KEK KKK KAKA KK EAA KEK ARERR | 


} 


Related Information 


regerror() — Return Error Message for Regular Expression 


Format 


#include <regex.h> 
size_t regerror(int errcode, const regex_t *preg, 
char *errbuf, size_t errbuf_size); 


Language Level: XPG4 


238 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Description 


The regerror() function finds the description for the error code errcode for the 
regular expression preg. The description for errcode is assigned to errbuf. The 
errbuf_size value specifies the maximum message size that can be stored (the size of 
errbuf). The description strings for errcode are: 


errcode Description String 

REG_NOMATCH regexec() failed to find a match. 

REG_BADPAT Invalid regular expression. 

REG_ECOLLATE Invalid collating element referenced. 

REG_ECTYPE Invalid character class type referenced. 

REG_EESCAPE Last character in regular expression is a \. 

REG_ESUBREG Number in \digit invalid, or error. 

REG_EBRACK [] imbalance. 

REG_EPAREN \(\) or ( imbalance. 

REG_EBRACE \{ \} imbalance. 

REG_BADBR Expression between \{ and \} is invalid. 

REG_ERANGE Invalid endpoint in range expression. 

REG_ESPACE Out of memory. 

REG_BADRPT 2, *, or + not preceded by valid regular 
expression. 

REG_ECHAR Invalid multibyte character. 

REG_EBOL * anchor not at beginning of regular 
expression. 

REG_EEOL $ anchor not at end of regular expression. 

REG_ECOMP Unknown error occurred during regcomp () 
call. 

REG_EEXEC Unknown error occurred during regexec () 
call. 


Note: This function is accessible only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


The regerror() returns the size of the buffer needed to hold the string that 
describes the error condition. 


Example that uses regerror() 


This example compiles an invalid regular expression, and prints an error message 
using the regerror() function. 
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#include <regex.htm> 
#include <stdio.h> 
#include <stdlib.h> 


int main(void) 
{ 
regex_t preg; 
char «pattern = "a[missing. bracket"; 
int rey 
char buffer[100] ; 


if (0 != (re = regcomp(&preg, pattern, REG_EXTENDED))) { 
regerror(rc, &preg, buffer, 100); 
printf("regcomp() failed with '%s'\n", buffer); 
exit (EXIT_FAILURE) ; 

} 


return 0; 


[KEK RK KER KK EAR KKK KKK KKK KKK AK K KK EA KKK IKKE IKKE KAKA KK 
The output should be similar to: 


regcomp() failed with '[] imbalance.' 


KKK AK KKK KK KKK KKK KKK KK KKK AK KK KKK AK KEIR KKK KKK KEK KEE KK | 


} 


Related Information 


regexec() — Execute Compiled Regular Expression 


Format 


#include <regex.h> 
int regexec(const regex_t *preg, const char *string, 
size_t nmatch, regmatch_t xpmatch, int eflags); 


Language Level: XPG4 
Thread Safe: NO. 
Description 


The regexec() function compares the null-ended string against the compiled 
regular expression preg to find a match between the two. 


The nmatch value is the number of substrings in string that the regexec() function 
should try to match with subexpressions in preg. The array you supply for pmatch 
must have at least nmatch elements. 


The regexec() function fills in the elements of the array pmatch with offsets of the 
substrings in string that correspond to the parenthesized subexpressions of the 
original pattern given to the regcomp() function to create preg. The zeroth element 
of the array corresponds to the entire pattern. If there are more than nmatch 
subexpressions, only the first nmatch - 1 are stored. If nmatch is 0, or if the 
REG_NOSUB flag was set when preg was created with the regcomp() function, the 
regexec() function ignores the pmatch argument. 
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The eflags flag defines customizable behavior of the regexec() function: 


errcode Description String 

REG_NOTBOL Indicates that the first character of string is 
not the beginning of line. 

REG_NOTEOL Indicates that the first character of string is 
not the end of line. 


When a basic or extended regular expression is matched, any given parenthesized 
subexpression of the original pattern could participate in the match of several 
different substrings of string. The following rules determine which substrings are 
reported in pmatch: 


1. If subexpression i in a regular expression is not contained within another 
subexpression, and it participated in the match several times, then the byte 
offsets in pmatch[i] will delimit the last such match. 


2. If subexpression i is not contained within another subexpression, and it did not 
participate in an otherwise successful match, the byte offsets in pmatch[i] will be 
-1. A subexpression does not participate in the match when any of following 
conditions are true: 


* * or \{ \} appears immediately after the subexpression in a basic regular 
expression. 


* *,?, or { } appears immediately after the subexpression in an extended 
regular expression, and the subexpression did not match (matched 0 times). 


* | is used in an extended regular expression to select this subexpression or 
another, and the other subexpression matched. 


3. If subexpression i is contained within another subexpression j, and i is not 
contained within any other subexpression that is contained within j, and a 
match of subexpression j is reported in pmatch[j], then the match or non-match 
of subexpression i reported in pmatch[i] will be as described in 1. and 2. above, 
but within the substring reported in pmatch[j] rather than the whole string. 

4. If subexpression i is contained in subexpression j, and the byte offsets in 
pmatch{j] are -1, then the offsets in pmatch[i] also will be -1.\ 


5. If subexpression i matched a zero-length string, then both byte offsets in 
pmatch{[i] will be the byte offset of the character or null terminator immediately 
following the zero-length string. 


If the REG_NOSUB flag was set when preg was created by the regcomp() function, 
the contents of pmatch are unspecified. If the REG_NEWLINE flag was set when 
preg was created, new-line characters are allowed in string. 


Return Value 

If a match is found, the regexec() function returns 0. If no match is found, the 
regexec() function returns REG_NOMATCH. Otherwise, it returns a nonzero value 
indicating an error. A nonzero return value can be used in a call to the regerror() 


function. 


Example that uses regexec () 
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#include <regex.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 
regex_t preg; 
char «string = "a very simple simple simple string"; 
char xpattern = "\\(sim[a-z]le\\) \\1"; 
int rc3 
size_t nmatch = 2; 


regmatch_t pmatch[2]; 


if (0 != (rc = regcomp(&preg, pattern, 0))) { 
printf("regcomp() failed, returning nonzero (%d)\n", rc); 
exit (EXIT_FAILURE) ; 

} 


if (0 != (rc = regexec(&preg, string, nmatch, pmatch, 0))) { 
printf("Failed to match '%s' with '%s',returning %d.\n", 
string, pattern, rc); 


else { 

printf("With the whole expression, " 
"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[@].rm_eo - pmatch[0].rm_so, &string[pmatch[0].rm_so], 
pmatch[0].rm_so, pmatch[0].rm_eo - 1); 

printf("With the sub-expression, " 
"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[1].rm_eo - pmatch[1].rm_so, &string[pmatch[1].rm_so], 
pmatch[1].rm_so, pmatch[1].rm_eo - 1); 


} 
regfree(&preg) ; 
return 0; 


[BRR R KKK KEKE A KKK KKK AKER KKK AKER IKKE IKKE AK KAKI A KEK 
The output should be similar to : 


With the whole expression, a matched substring "simple simple" is found 
at position 7 to 19. 

With the sub-expression, a matched substring "simple" is found 

at position 7 to 12. 


KKK AK KKK KK KKK KKK KKK KK KKK KKK KKK AKA KKK AK KKK KKK KKK IKKE KA KK EAA ERA K KERR EEK | 


} 


Related Information 


regfree() — Free Memory for Regular Expression 


Format 
#include <regex.h> 
void regfree(regex_t *preg); 


Language Level: XPG4 


Description 
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The regfree() function frees any memory that was allocated by the 
regcomp()function to implement the regular expression preg. After the call to the 
regfree() function, the expression that is defined by preg is no longer a compiled 
regular or extended expression. 


Note: This function is accessible only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 

There is no return value. 

Example that uses regfree() 

This example compiles an extended regular expression. 


#include <regex.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main(void) 

{ 
regex_t preg; 
char *xpattern = ".*(simple).*"; 
int YC3 


if (0 != (rc = regcomp(&preg, pattern, REG_EXTENDED))) { 
printf("regcomp() failed, returning nonzero (%d)\n", rc); 
exit (EXIT_FAILURE) ; 

} 


regfree(&preg) ; 
printf("regcomp() is successful.\n"); 
return 0; 


[RRR RK ERA KK ERK KEIR KEK K EK KKK AKER KER AK KEA KK AAKE AK KEI KER ARE 
The output should be similar to: 


regcomp() is successful. 


KKK KKK KKK KK AKKEA KKK KKK KKK KKK AKER AK KEIRA KKK AREA AKER EKER | 


} 


Related Information 


remove() — Delete File 


Format 
#include <stdio.h> 
int remove(const char *filename) ; 


Language Level: ANSI 


Description 
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The remove() function deletes the file specified by filename. If the filename contains 
the member name, the member is removed or the file is deleted. 


Note: You cannot remove a nonexistent file or a file that is open. 
Return Value 


The remove() function returns 0 if it successfully deletes the file. A nonzero return 
value indicates an error. 


Example that uses remove() 


When you call this example with a file name, the program attempts to remove that 
file. It issues a message if an error occurs. 


#include <stdio.h> 
int main(int argc, char ** argv) 


if ( argc != 2 ) 
printf( "Usage: %s fn\n", argv[0] ); 
else 
if ( remove( argv[1] ) != 0 ) 
perror( "Could not remove file" ); 


} 


Related Information 


rename() — Rename File 


Format 


#include <stdio.h> 
int rename(const char *oldname, const char *newname) ; 


Language Level: ANSI 
Description 


The rename() function renames the file specified by oldname to the name given by 
newname. The oldname pointer must specify the name of an existing file. The 
newname pointer must not specify the name of an existing file. You cannot rename 
a file with the name of an existing file. You also cannot rename an open file. 


The file formats that can be used to satisfy the new name depend on the format of 
the old name. The following table shows the valid file formats that can be used to 
specify the old file name and the corresponding valid file formats for the new 
name. 


If the format for both new name and old name is lib/file(member), then the file 


cannot change. If the file name changes, rename will not work. For example, the 
following is not valid: lib/file1(member1) lib/file2(memberl1). 
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Old Name New Name 
lib /file(member) lib /file(member), lib/file, file, file(member) 
lib/file lib/file, file 
file lib/file, file 
file(member) lib /file(member), lib/file, file, file(member) 


Return Value 


The rename() function returns 0 if successful. On an error, it returns a nonzero 
value. 


Example that uses rename() 


This example takes two file names as input and uses rename() to change the file 
name from the first name to the second name. 


#include <stdio.h> 


int main(int argc, char ** argv ) 
{ 
if ( argc != 3 ) 
printf( "Usage: %s old_fn new_fn\n", argv[0] ); 
else if ( rename( argv[1], argv[2] ) != 0) 
perror ( "Could not rename file" ); 
} 


Related Information 


rewind() — Adjust Current File Position 


Format 

#include <stdio.h> 

void rewind(FILE *stream) ; 
Language Level: ANSI 


Description 


The rewind() function repositions the file pointer associated with stream to the 
beginning of the file. A call to the rewind() function is the same as: 


(void) fseek(stream, OL, SEEK_SET); 
except that the rewind () function also clears the error indicator for the stream. 
The rewind() function is not supported for files opened with type=record. 
Return Value 
There is no return value. 
The value of errno may be set to: 
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Value Meaning 


EBADF 
The file pointer or descriptor is not valid. 


ENODEV 
Operation attempted on a wrong device. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


Example that uses rewind() 


This example first opens a file myfile for input and output. It writes integers to the 
file, uses rewind() to reposition the file pointer to the beginning of the file, and 
then reads in the data. 


#include <stdio.h> 
FILE «stream; 


int datal, data2, data3, data4; 
int main(void) 


datal = 1; data2 = -37; 


/* Place data in the file */ 
stream = fopen("mylib/myfile", "wt"); 
fprintf(stream, "%d %d\n", datal, data2); 


/* Now read the data file */ 
rewind(stream) ; 
fscanf(stream, "%d", &data3); 
fscanf(stream, "%d", &data4); 
printf("The values read back in are: %d and %d\n", 
data3, data4); 
} 


[KRKRKKEREKERKEKEREKRER Output should be similar to: ******kk*kKKEKK 


The values read back in are: 1 and -37 


*/ 


Related Information 


_Rfeod() —Force the End-of-Data 


Format 
#include <recio.h> 


int _Rfeod(_RFILE fp); 
Language Level: ILE C Extension 
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Description 


The Rfeod() function forces an end-of-data condition for a device or member 
associated with the file specified by fp. Any outstanding updates, deletes or writes 
that the system is buffering will be forced to nonvolatile storage. If a database file 
is open for input, any outstanding locks will be released. 


The _Rfeod() function positions the file to *END unless the file is open for 
multi-member processing and the current member is not the last member in the 
file. If multi-member processing is in effect and the current member is not the last 
member in the file, Rfeod() will open the next member of the file and position it 
to *START. 


The _Rfeod() function is valid for all types of files. 
Return Value 


The _Rfeod() function returns 1 if multi-member processing is taking place and the 
next member has been opened. EOF is returned if the file is positioned to *END. If 
the operation is unsuccessful, zero is returned. The value of errno may be set to 
EIOERROR (a non-recoverable error occurred) or ELORECERR (a recoverable I/O 
ertor occurred), See lable 12 on page 43 and able d.an page 454 for ermo 
settings. 


Example that uses Rfeod() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 


{ 


_RFILE  *in; 
char new_purchase[21] = "PEAR 1002022244"; 
/* Open the file for processing in keyed sequence. x*/ 


if ( (in = _Ropen("MYLIB/T1677RD4", "rr+, arrseq=N")) == NULL ) 
printf("Open failed\n"); 
exit(1); 

}; 

/* Update the first record in the keyed sequence. */ 


_Rlocate(in, NULL, 0, __ FIRST); 
_Rupdate(in, new_purchase, 20); 


/* Force the end of data. */ 


_Rfeod(in); 


Related Information 


_Rfeov() —Force the End-of-File 
Format 
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#include <recio.h> 

int _Rfeov(_RFILE *fp); 

Language Level: ILE C Extension 

Description 

The Rfeov() function forces an end-of-volume condition for a tape file that is 
associated with the file that is specified by fp. The _Rfeov()function positions the 
file to the next volume of the file. If the file is open for output, the output buffers 
will be flushed. 

The _Rfeov() function is valid for tape files. 

Return Value 

The Rfeov() function returns 1 if the file has moved from one volume to the next. 


It will return EOF if it is called while processing the last volume of the file. It will 
return zero if the operation is unsuccessful. The value of errno may be set to 


EIOERROR (a non-recoverable error occurred) or ELORECERR (a recoverable I/O 
error occurred). See [able 12 on page 451] and for errno 
settings. 


Example that uses Rfeov() 
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#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 


int main(void) 

{ 
_RFILE *tape; 
RFILE *fp; 
char buf [92]; 
int i, feov2; 


/* Open source physical file containing C source. */ 


if (( fp = _Ropen ( "QCSRC(T1677SRC)", "rr blkrcd=y" )) == NULL ) 
{ 

printf ( "could not open C source file\n" ); 

exit (1); 
} 


/* Open tape file to receive C source statements x/ 
if (( tape = Ropen ( "T1677TPF", "wr lrecl=92 blkrcd=y" )) == NULL ) 
{ 


printf ( "could not open tape file\n" ); 
exit (2 )3 


/* Read the C source statements, find their sizes */ 
/* and add them to the tape file. x/ 


while (( _Rreadn ( fp, buf, sizeof(buf), _ DFT )) -> num_bytes != EOF 


{ 
for ( i = sizeof(buf) - 1 ; buf[i] == ' ' && i > 12; --i ); 
i = (i == 12) ? 80: (1-12); 
memmove( buf, buf+1l2, i ); 
_Rwrite ( tape, buf, i ); 
} 
feov2 = Rfeov (fp); 


_Rclose ( fp ); 


_Rclose ( tape ); 
} 


Related Information 


_Rformat() —Set the Record Format Name 


Format 
#include <recio.h> 


void _Rformat(_RFILE *fp, char *fmt); 

Language Level: ILE C Extension 

Description 

The _Rformat() function sets the record format to fmt for the file specified by fp. 


The _Rformat() function is valid for multi-format logical database, DDM files, 
display, ICF and printer files. 
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The fmt parameter is a null-ended C string. The fmt parameter must be in 
uppercase. 


Return Value 


The Rformat() function returns void. See Hable 12 on page 451] and [able 14 on) 


for errno settings. 
Example that uses Rformat() 
This example shows how _Rformat() is used. 


#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 
#include <string.h> 


int main(void) 


char buf [40]; 
int re = 1; 
_RFILE *purf 

_RFILE «dailyf; 


/* Open purchase display file and daily transaction file */ 
if ( ( purf = _Ropen ( "MYLIB/T1677RD3", "“ar+,indicators=y" )) == NULL ) 
{ 


printf ( "Display file did not open.\n" ); 
exit (1); 
} 


if ( ( dailyf = _Ropen ( "MYLIB/T1677RDA", "wr,commit=y") ) == NULL ) 
{ 


printf ( "Daily transaction file did not open.\n" ); 
exit (2 )3 
} 


/* Select purchase record format */ 
_Rformat ( purf, "PURCHASE" ); 


/* Invite user to enter a purchase transaction. */ 
/* The _Rwrite function writes the purchase display. */ 
_Rwrite ( purf, "", 0); 

_Rreadn ( purf, buf, sizeof(buf), DFT ); 


/* Update daily transaction file x/ 
rc = (( _Rwrite ( dailyf, buf, sizeof(buf) ))->num_bytes ); 
/* If the databases were updated, then commit the transaction. */ 
/* Otherwise, rollback the transaction and indicate to the */ 
/* user that an error has occurred and end the application. */ 
if (rc ) 
_Rcommit ( "Transaction complete" ); 
} 
else 
{ 
_Rrollbck ( ); 
_Rformat ( purf, "ERROR" ); 
} 


_Rclose ( purf ); 
_Rclose ( dailyf ); 
} 
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Related Information 


_Rindara() —Set Separate Indicator Area 


Format 
#include <recio.h> 


void _Rindara(_RFILE *fp, char *indic_buf); 

Language Level: ILE C Extension 

Thread Safe: NO. 

Description 

The _Rindara() function registers indic_buf as the separate indicator area to be 
used by the file specified by fp. The file must be opened with the keyword 
indicators=Y on the _Ropen() function. The DDS for the file should specify also 
that a separate indicator area is to be used. It is generally best to initialize a 
separate indicator area explicitly with ’0’ (character) in each byte. 


The _Rindara() function is valid for display, ICF, and printer files. 


Return Value 


The Rindara() function returns void. See Hable 12 on page 451] and [able 14 onl 


for errno settings. 


Example that uses Rindara() 
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#include <stdio.h> 

#include <recio.h> 

#include <stdlib.h> 
#include <string.h> 
#define PF03 2 
#define IND OFF '0' 
#define IND_ON '1' 


int main(void) 

{ 
char buf [40] ; 
int re = 1; 
_SYSindara ind_area; 
_RFILE *purf 
_RFILE «dailyf; 


/* Open purchase display file and daily transaction file */ 
if ( ( purf = _Ropen ( "MYLIB/T1677RD3", "“ar+,indicators=y" )) == NULL ) 
{ 


printf ( "Display file did not open.\n" ); 
exit (1 )3 


if ( ( dailyf = _Ropen ( "MYLIB/T1677RDA", "wr,commit=y") ) == NULL ) 
{ 


printf ( "Daily transaction file did not open.\n" ); 
exit (2 )3 


/* Associate separate indicator area with purchase file */ 
_Rindara ( purf, ind_area ); 

/* Select purchase record format */ 

_Rformat ( purf, "PURCHASE" ); 

/* Invite user to enter a purchase transaction. */ 
/* The _Rwrite function writes the purchase display. */ 
_Rwrite ( purf, "", 0); 

_Rreadn ( purf, buf, sizeof(buf), DFT ); 


/* While user is entering transactions, update daily and */ 
/* monthly transaction files. */ 
while ( rc && ind_area[PFO3] == IND OFF ) 
{ 
rc = (( _Rwrite ( dailyf, buf, sizeof(buf) ))->num_bytes ); 
/* If the databases were updated, then commit transaction */ 
/* otherwise, rollback the transaction and indicate to the */ 
/* user that an error has occurred and end the application. */ 
if (rc ) 
{ 
_Rcommit ( "Transaction complete" ); 
} 
else 
_Rrollbck ( ); 
_Rformat ( purf, "ERROR" ); 
} 


_Rwrite ( purf, "", 0); 
_Rreadn ( purf, buf, sizeof(buf), DFT ); 
} 


_Rclose ( purf ); 
_Rclose ( dailyf ); 
} 


Related Information 


_Riofbk() —Obtain I/O Feedback Information 


Format 
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#include <recio.h> 
#include <xxfdbk.h> 
_XXIOFB_T * _Riofbk(_RFILE *fp); 


Language Level: ILE C Extension 
Description 


The _Riofbk() function returns a pointer to a copy of the I/O feedback area for the 
file that is specified by fp. 


The _Riofbk() function is valid for all types of files. 


Return Value 


The _Ri a : function returns NULL if an error occurs. See [able 12 on page 451] 


and for errno settings. 


Example that uses Riofbk() 


#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 
typedef struct { 
char name[20] ; 
char address[25]; 
} formatl ; 
typedef struct { 
char name[8]; 
char password[10]; 
} format2 ; 
typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


{ 


_RFILE *fp; /* File pointer */ 

_RIOFB_T *rfb; /*Pointer to the file's feedback structure x/ 

_XXIOFB_T *iofb; /* Pointer to the file's feedback area x/ 

formats buf, in_buf, out_buf; /* Buffers to hold data */ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", "ar+" )) == NULL ) 
{ 
printf ( "Could not open file\n" ); 


exit (1); 
_Racquire ( fp,"DEVICE1" ); /* Acquire another device. Replace 
*/ 
/* with actual device name. */ 
_Rformat ( fp,"FORMAT1" ); /* Set the record format for the */ 
/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. sei 


_Rpgmdev ( fp,"DEVICE2" ); /* Change the default program device. */ 
/* Replace with actual device name. */ 
_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 


sizeof (out_buf )); 
_Rreadindv ( fp, &buf, sizeof(buf), DFT ); 
/* Read from the first device that */ 
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/* enters data - device becomes x/ 
/* default program device. */ 
/* Determine which terminal responded first. */ 
iofb = Riofbk ( fp ); 
if ( !strncmp ( "FORMAT1 ", iofb -> rec_format, 10 )) 


_Rrelease ( fp, "DEVICE1" ); 


else 


{ 
} 


/* Continue processing. */ 
printf ( "Data displayed is %45.45s\n", &buf); 
_Rclose ( fp ); 


_Rrelease(fp, "DEVICE2" ); 


} 


Related Information 


_Rlocate() —Position a Record 


Format 


#include <recio.h> 


_RIOFB_T *_Rlocate(_RFILE *fp, void *key, int klen_rrn, int opts); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rlocate() function positions to the record in the file associated with fp and 
specified by the key, klen_rrn and opts parameters. The _Rlocate() function locks 
the record specified by the key, klen_rrn and opts parameters unless __NO_LOCK is 
specified. 


The _Rlocate() function is valid for database and DDM files that are opened with 
the _Ropen() function. The following are valid parameters of the 
_Rlocate() function. 


key Points to a string containing the key fields to be used for positioning. 


klen_rrn 
Specifies the length of the key that is used if positioning by key or the 
relative record number if positioning by relative record number. 


opts Specifies positioning options to be used for the locate operation. The 
possible macros are: 


__DFT 


Default to _ KEY_EQ and lock the record for update if the file is 
open for updating. 


__END 
Positions to just after the last record in a file. There is no record 
that is associated with this position. 
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__END_FRC 


Positions to just after the last record in a file. All buffered changes 
are made permanent. There is no record that is associated with this 
position. 


__FIRST 


Positions to the first record in the access path that is currently 
being used by fp. The key parameter is ignored. 


__KEY_EQ 


Positions to the first record with the specified key. 


__KEY_GE 


Positions to the first record that has a key greater than or equal to 
the specified key. 


__KEY_GT 


Positions to the first record that has a key greater than the 
specified key. 


__KEY_LE 


Positions to the first record that has a key less than or equal to the 
specified key. 


__KEY_LT 


Positions to the first record that has a key less than the specified 
key. 


__KEY_NEXTEQ 


Positions to the next record that has a key equal to the key value 
with a length of klen_rrn, at the current position. The key parameter 
is ignored. 


__KEY_NEXTUNQ 


Positions to the next record with a unique key from the current 
position in the access path. The key parameter is ignored. 


KEY_PREVEQ 


Positions to the previous record with a key equal to the key value 
with a length of klen_rrn, at the current position. The key parameter 
is ignored. 


__KEY_PREVUNQ 


Positions to the previous record with a unique key from the 
current position in the access path. The key parameter is ignored. 


__ LAST 


Positions to the last record in the access path that is currently 
being used by fp. The key parameter is ignored. 


__ NEXT 


Positions to the next record in the access path that is currently 
being used by fp. The key parameter is ignored. 


__PREVIOUS 


Positions to the previous record in the access path that is currently 
being used by fp. The key parameter is ignored. 


__RRN_EQ 


Positions to the record that has the relative record number 
specified on the klen_rrn parameter. 
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__START 
Positions to just before the first record in the file. There is no 
record that is associated with this position. 


__START_FRC 
Positions to just before the first record in a file. There is no record 
that is associated with this position. All buffered changes are made 
permanent. 


__DATA_ONLY 
Positions to data records only. Deleted records will be ignored. 


__KEY_NULL_MAP 
The NULL key map is to be considered when locating to a record 
by key. 

__NO_LOCK 
The record that is positioned will not be locked. 


__NO_POSITION 
The position of the file is not changed, but the located record will 
be locked if the file is open for update. 


__PRIOR 
Positions to just before the requested record. 


If you specify the start and end options (_START, _ START_FRC, __END or 
__END_FRC) with any other options, the other options are ignored. 


If you are positioned to _ START or __ END and perform a _Rreads operation, 
errno is set to EIOERROR. 


Return Value 


The _Rlocate() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the _Rlocate() operation is successful, the num_bytes field contains 1. If 
__START, _ START_FRC, _END or __END_FRC are specified, the num_bytes field 
is set to EOF. If the Rlocate() operation is unsuccessful, the num_bytes field 
contains zero. The key and rrn fields are updated, and the key field will contain the 
complete key even if a partial key is specified. 


The value of errno may be set to: 


Table 5. 

Value Meaning 

EBADKEYLN The key length that is specified is not valid. 
ENOTREAD The file is not open for read operations 
EIOERROR A non-recoverable I/O error occurred. 
EIORECERR A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses _Rlocate() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 


{ 


_RFILE  *in; 
char new_purchase[21] = "PEAR 1002022244"; 
/* Open the file for processing in keyed sequence. x/ 


if ( (in = _Ropen("MYLIB/T1677RD4", "rr+, arrseq=N")) == NULL ) 
printf("Open failed\n"); 
exit(1); 

Ks 

/* Update the first record in the keyed sequence. */ 


_Rlocate(in, NULL, 0, __ FIRST); 
_Rupdate(in, new_purchase, 20); 


/* Force the end of data. x/ 
_Rfeod(in); 


_Rclose(in); 


} 


Related Information 


_Ropen() — Open a Record File for I/O Operations 


Format 
#include <recio.h> 


_RFILE *_Ropen(const char * filename, const char * mode, ...); 
Language Level: ILE C Extension 
Description 


The _Ropen() function opens the record file specified by filename according to the 
mode parameter, which may be followed by optional parameters, if the varparm 
keyword parameter is specified in the mode parameter. The open mode and 
keyword parameters may be separated by a comma and one or more spaces. The 
_Ropen() function does not dynamically create database files for you. All of the 
files you refer to in the _Ropen() function must exist, or the open operation will 
fail. 


Files that are opened by the _Ropen() function are closed implicitly when the 
activation group they are opened in, is ended. If a pointer to a file opened in one 
activation group is passed to another activation group and the opening activation 
group is ended, the file pointer will no longer be valid. 


The _Ropen() function applies to all types of files. The filename variable is any valid 
iSeries system file name. 
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The mode parameter specifies the type of access that is requested for the file. It 
contains an open mode that is followed by optional keyword parameters. The mode 
parameter may be one of the following values: 


Mode Description 


ir Open an existing file for reading records. 

wr Open an existing file for writing records. If the file contains data, the 
content is cleared unless the file is a logical file. 

ar Open an existing file for writing records to the end of the file (append). 

1r+ Open an existing file for reading, writing or updating records. 


wr+ Open an existing file for reading, writing or updating records. If the file 
contains data, the content is cleared unless the file is a logical file. 


art Open an existing file for reading and writing records. All data is written to 
the end of the file. 
The mode may be followed by any of the following keyword parameters: 


Keyword 
Description 


arrseq=value 
Where value can be: 


Y Specifies that the file is processed in arrival sequence. 


N Specifies that the file is processed using the access path that is 
used when the file was created. This is the default. 


blkrced=value 
Where value can be: 


Y Performs record blocking. The iSeries system determines the most 
efficient block size for you. This parameter is valid for database, 
DDM, diskette and tape files. It is only valid for files opened for 
input-only or output-only (modes rr, wr, or ar). 


N Does not perform record blocking. This is the default. 


ccsid=value 
Specifies the CCSID that is used for translation of the file. The default is 0 
which indicates that the job CCSID is used. 


commit=value 
Where value can be: 


Y Specifies that the database file is opened under commitment 
control. Commitment control must have been set up prior to this. 


N Specifies that the database file is not opened under commitment 
control. This is the default. 


dupkey=value 
value can be: 


Y Duplicate key values will be flagged in the _RIOFB_T structure. 
N Duplicate key values will not be flagged. This is the default. 


indicators=value 
Indicators are valid for printer, display, and ICF files. value can be: 
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Y The indicators that are associated with the file are returned in a 
separate indicator area instead of in the I/O buffers. 


N The indicators are returned in the I/O buffers. This is the default. 


lrecl=value 
The length, in bytes, for fixed length records, and the maximum length for 
variable length records. This parameter is valid for diskette, display, 
printer, tape, and save files. 


nullcap=value 
Where value can be: 


Y The program is capable of handling null fields in records. This is 
valid for database and DDM files. 
N The program cannot handle null fields in records. This is the 
default. 
riofb=value 
Where value can be: 
Y All fields in the _RIOFB_T structure are updated by any I/O 


operation that returns a pointer to the _RIOFB_T structure. 
However, the blk_filled_by field is not updated when using the 
_Rreadk function. This is the default. 


N Only the num_bytes field in the _RIOFB_T structure is updated. 


rtncode=value 
Where value can be: 


Y Use this option to bypass exception generation and handling. This 
will improve performance in the end-of-file and record-not-found 
cases. If the end-of-file is encountered, num_bytes will be set to 
EOF, but no errno values will be generated. If no record is found, 
num_bytes will be set to zero, and errno will be set to 
EIORECERR. This parameter is only valid for database and DDM 
files. For DDM files, num_bytes is not updated for _Rfeod. 


N The normal exception generation and handling process will occur 
for the cases of end-of-file and record-not-found. This is the 
default. 


secure=value 
Where value can be: 


Y Secures the file from overrides. 
N Does not secure the file from overrides. This is the default. 


splfname=(value) 
For spooled output only. Where value can be: 


*FILE The name of the printer file is used for the spooled output file 
name. 


spool-file-name 
Specify the name of the spooled output file. A maximum of 10 
characters can be used. 


usrdta=(value) 
To specify, for spooled output only, user-specified data that identifies the 
file. 
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user-data 
Specify up to 10 characters of user-specified text. 


varparm=(list) 
Where (list) is a list of optional keywords indicating which optional 
parameters will be passed to _Ropen(). The order of the keywords within 
the list indicates the order that the optional parameters will appear after 
the mode parameter. The following is a valid optional keyword: 


Ivlchk The lvlchk keyword is used in conjunction with the lvlchk option 
on #pragma mapinc. When this keyword is used, a pointer to an 
object of type _LVLCHK_T (generated by #pragma mapinc) must 
be specified after the mode parameter on the _Ropen() function. 
For more details on this pointer, see the Ivlchk option of #pragma 
mapinc in the WebSphere Development Studio: ILE C/C++ 
Programmer's Guide. 


vlr=value 
Variable length record, where value is the minimum length of bytes of a 
record to be written to the file. The value can equal -1, or range from 0 to 
the maximum record length of the file. This parameter is valid for database 
and DDM files. 


When VLR processing is required, _Ropen() will set min_length field. If the 
default value is not used, the minimum value that is provided by the user 
will be directly copied into min_length field. If the default value is 
specified, Ropen() gets the minimum length from DB portion of the open 
data path. 


Return Value 


The _Ropen() function returns a pointer to a structure of type _RFILE if the file is 
opened successfully. It returns NULL if opening the file is unsuccessful. 


The value of errno may be set to: 


Value Meaning 


EBADMODE 
The file mode that is specified is not valid. 


EBADNAME 
The file name that is specified is not valid. 


ENOTOPEN 
The file is not open. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 an page 451] and Hable 14 on page 455 for errno settings. 


Example that uses _Ropen() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 
_RFILE «fp; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 


else 


/* Do some processing */; 


_Rclose ( fp ); 
} 


Related Information 


_Ropnfbk() — Obtain Open Feedback Information 


Format 


#include <recio.h> 
#include <xxfdbk.h> 


_XXOPFB_T * Ropnfbk(_RFILE *fp); 
Language Level: ILE C Extension 
Description 


The _Ropnfbk() function returns a pointer to a copy of the open feedback area for 
the file that is specified by fp. 


The _Ropnfbk() function is valid for all types of files. 


Return Value 


The _Ropnfbk() function returns NULL if an error occurs. See 


and for errno settings. 


Example that uses Ropnfbk() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE *fp; 
_XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
} 


/* Get the library and file names of the file opened. */ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


_Rclose ( fp ); 
} 


Related Information 


_Rpgmdev() — Set Default Program Device 
Format 
#include <recio.h> 
int _Rpgmdev(_RFILE «fp, char *dev); 
Language Level: ILE C Extension 
Thread Safe: NO. 


Description 


The _Rpgmdev() function sets the current program device for the file that is 
associated with fp to dev. You must specify the device in uppercase. 


The dev parameter is a null-ended C string. 

The _Rpgmdev() function is valid for display, ICF, and printer files. 

Return Value 

The _Rpgmdev() function returns 1 if the operation is successful or zero if the 


device specified has not been acquired for the file. See [able 12 on page 451] and 
Fs or eed orc ro setae 


Example that uses _Rpgmdev() 
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#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 


typedef struct { 
char name[20]; 
char address[25]; 
} formatl ; 


typedef struct { 

char name[8]; 

char password[10]; 
} format2 ; 


typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


{ 


_RFILE fp; /* File pointer */ 
_RIOFB_T *rfb; /*Pointer to the file's feedback structure */ 
formats buf, in_buf, out_buf; /* Buffers to hold data x*/ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", "“ar+" )) == NULL ) 
{ 
printf ( "Could not open file\n" ); 


exit (1); 
} 


_Rpgmdev ( fp,"DEVICE2" );/* Change the default program device. */ 
/* Replace with actual device name. */ 


_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = _Rwrite ( fp, "", 0);  /* Set up the display. xi 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 
sizeof (out_buf )); 
/* Continue processing. */ 


_Rclose ( fp ); 
} 


Related Information 


_Rreadd() — Read a Record by Relative Record Number 


Format 
#include <recio.h> 


_RIOFB_T *_Rreadd (_RFILE *fp, void *buf, size_t size, 
int opts, long rrn); 


Language Level: ILE C Extension 
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Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreadd() function reads the record that is specified by rrn in the arrival 
sequence access path for the file that is associated with fp. The _Rreadd() function 
locks the record specified by the rrn unless __NO_LOCK is specified. If the file is a 
keyed file, the keyed access path is ignored. Up to size number of bytes are copied 
from the record into buf (move mode only). 


The following parameters are valid for the _Rreadd() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


rm The relative record number of the record to be read. 


opts Specifies the processing and access options for the file. The possible 
options are: 


DFT 


If the file is opened for updating, then the record being read is 
locked for update. The previously locked record will no longer be 
locked. 


__NO_LOCK 
Does not lock the record being positioned to. 


The _Rreadd() function is valid for database, DDM and display (subfiles) files. 
Return Value 


The _Rreadd() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the _Rreadd() operation is successful the num_byftes field is set to the 
number of bytes transferred from the system buffer to the user’s buffer (move 
mode) or the record length of the file (locate mode). If blkrcd=Y and riofb=Y are 
specified, the blk_count and the blk_filled_by fields of the _RIOFB_T structure are 
updated. The key and rrn fields are also updated. If the file associated with fp is a 
display file, the sysparm field is updated. If it is unsuccessful, the num_bytes field 
is set to a value less than size and errno will be changed. 


The value of errno may be set to: 
Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rreadd() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE fp; 
“XXOPFB_T —-*opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 


/* Get the library and file names of the file opened. */ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the second record. x/ 
_Rreadd ( fp, NULL, 20, _ DFT, 2 ); 
printf ( "Second record: %10.10s\n", *(fp->in_buf) ); 


_Rclose ( fp ); 
} 


Related Information 


_Rreadf() — Read the First Record 


Format 
#include <recio.h> 


_RIOFB_T *_Rreadf (_RFILE *fp, void *buf, size_t size, int opts); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreadf() function reads the first record in the access path that is currently 
being used for the file specified by fp. The access path may be keyed sequence or 
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arrival sequence. The _Rreadf() function locks the first record unless _ NO_LOCK 
is specified. Up to size number of bytes are copied from the record into buf (move 
mode only). 


The following are valid parameters for the _Rreadf() function. 


buf This parameter points to the buffer where the data that is read is to be 
stored. If locate mode is used, this parameter must be set to NULL. 


size This parameter specifies the number of bytes that are to be read and stored 
in buf. If locate mode is used, this parameter is ignored. 


opts This parameter specifies the processing and access options for the file. The 
P Pp P Pp 8 P 
possible options are: 


DFT 


If the file is opened for updating, then the record being read or 
positioned to is locked for update. The previously locked record 
will no longer be locked. 


__NO_LOCK 
Does not lock the record being positioned to. 


The Rreadf() function is valid for database and DDM files. 
Return Value 


The _Rreadf() function returns a pointer to the _RIOFB_T structure that is 
specified by fp. If the _Rreadf() operation is successful the num_bytes field is set to 
the number of bytes transferred from the system buffer to the user’s buffer (move 
mode) or the record length of the file (locate mode). The key and rrn fields are 
updated. If record blocking is taking place, the blk_count and blk_filled_by fields 
are updated. The num_bytes field is set to EOF if the file is empty. If it is 
unsuccessful, the num_bytes field is set to a value less than size, and errno is 
changed. 


The value of errno may be set to: 


Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and Hable 14 on page 455 for errno settings. 


Example that uses _Rreadf() 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE «fp; 
_XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
} 


/* Get the library and file names of the file opened. x/ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the first record. */ 
_Rreadf ( fp, NULL, 20, _DFT ); 
printf ( "First record: %10.10s\n", *(fp->in_buf) ); 


/* Delete the first record. */ 
_Rdelete ( fp ); 


_Rclose ( fp ); 
} 


Related Information 


_Rreadindv() — Read from an Invited Device 


Format 


#include <recio.h> 


_RIOFB_T *_Rreadindv(_RFILE «fp, void *buf, size_t size, int opts); 
Language Level: ILE C Extension 

Thread Safe: NO. 

Description 

The Rreadindv() function reads data from an invited device. 


The following are valid parameters for the _Rreadindv() function. 
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buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


opts Specifies the processing options for the file. Possible values are: 


DFT 


If the file is opened for updating, then the record being read or 
positioned to is locked. Otherwise, the option is ignored. 


The _Rreadindv() function is valid for display and ICF files. 
Return Value 


The _Rreadindv() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rreadindv() function is successful, the num_bytes field 
is set to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The sysparm and rm 
(for subfiles) fields are also updated. The num_bytes field is set to EOF if the file is 
empty. If the _Rreadindv() function is unsuccessful, the num_bytes field is set to a 
value less than the value of size and the errno will be changed. 


The value of errno may be set to: 


Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rreadindv() 
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#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 
typedef struct { 


char name[20]; 
char address[25]; 


} formatl ; 
typedef struct { 


char name[8]; 
char password[10]; 


} format2 ; 
typedef union { 


formatl fmt1; 
format2 fmt2; 


} formats ; 
int main(void) 


{ 


} 


/* 


/* 


/* 


_RFILE = *fp; /* File pointer 

ee xr fb; /* Pointer to the file's feedback structure 
eae *xiofb; /* Pointer to the file's feedback area 
te buf, in_buf, out_buf /* Buffers to hold data 
anch the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", "“ar+" )) == NULL ) 
{ 
printf ( "Could not open file\n" ); 


exit (1); 
} 
_Racquire ( fp,"DEVICE1" ); /* Acquire another device. Replace */ 
/* with actual device name. */ 
_Rformat ( fp,"FORMAT1" ); /* Set the record format for the «/ 
/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 


_Rpgmdev ( fp,"DEVICE2" ); /* Change the default program device. */ 
/* Replace with actual device name. */ 
_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 


sizeof (out_buf )); 
_Rreadindv ( fp, &buf, sizeof(buf), DFT ); 
/* Read from the first device that */ 


/* enters data - device becomes x/ 
/* default program device. */ 
Determine which terminal responded first. */ 


jiofb = Riofbk ( fp ); 
if ( !strncmp ( "FORMAT1 ", iofb -> rec_format, 10 )) 


{ 
_Rrelease ( fp, "DEVICE1" ); 
} 
else 
{ 
_Rrelease(fp, "DEVICE2" ); 
} 
Continue processing. */ 


printf ( "Data displayed is %45.45s\n", &buf); 
_Rclose ( fp ); 


Related Information 
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_Rreadk() — Read a Record by Key 
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Format 
#include <recio.h> 


_RIOFB_T *_Rreadk(_RFILE *fp, void *buf, size_t size, 
int opts, void «key, unsigned int keylen); 


Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreadk() function reads the record in the keyed access path that is currently 
being used for the file that is associated with fp. Up to size number of bytes are 
copied from the record into buf (move mode only). The _Rreadk() function locks 
the record positioned to unless __ NO_LOCK is specified. You must be processing 
the file using a keyed sequence path. 

The following parameters are valid for the _Rreadk() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


key Points to the key to be used for reading. 
keylen Specifies the total length of the key to be used. 


opts Specifies the processing options for the file. Possible values are: 


__DFT 

Default to _ KEY_EQ. 
__KEY_EQ 

Positions to and reads the first record that has the specified key. 
__KEY_GE 


Positions to and reads the first record that has a key greater than 
or equal to the specified key. 


__KEY_GT 
Positions and reads to the first record that has a key greater than 
the specified key. 


__KEY_LE 
Positions to and reads the first record that has a key less than or 
equal to the specified key. 
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__KEY_LT 
Positions to and reads the first record that has a key less than the 
specified key. 

__KEY_NEXTEQ 


Positions to and reads the next record that has a key equal to the 
key value at the current position. The key parameter is ignored. 


__KEY_NEXTUNQ 
Positions to and reads the next record with a unique key from the 
current position in the access path. The key parameter is ignored. 


__KEY_PREVEQ 
Positions to and reads the last record that has a key equal to the 
key value at the current position. The key parameter is ignored. 


__KEY_PREVUNQ 
Positions to and reads the previous record with a unique key from 
the current position in the access path. The key parameter is 
ignored. 


__NO_LOCK 
Do not lock the record for updating. 


The positioning options are mutually exclusive. 


The following options may be combined with the positioning options using the 
bit-wise OR (|) operator. 


__KEY_NULL_MAP 
The NULL key map is to be considered when reading a record by key. 


__NO_LOCK 
The record that is positioned will not be locked. 


The Rreadk() function is valid for database and DDM files. 
Return Value 


The _Rreadk() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the _Rreadk() operation is successful the num_byftes field is set to the 
number of bytes transferred from the system buffer to the user’s buffer (move 
mode) or the record length of the file (locate mode). The key and rrn fields will be 
updated. The key field will always contain the complete key if a partial key is 
specified. When using record blocking with _Rreadk(), only one record is read into 
the block. Thus there are zero records remaining in the block and the blk_count 
field of the _RIOFB_T structure will be updated with 0. The blk_filled_by field is 
not applicable to _Rreadk() and is not updated. If the record specified by key 
cannot be found, the num_bytes field is set to zero. If you are reading a record by a 
partial key, then the entire key is returned in the feedback structure. If it is 
unsuccessful, the num_bytes field is set to a value less than size and errno will be 
changed. 


The value of errno may be set to: 
Value Meaning 


EBADKEYLN 
The key length specified is not valid. 
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ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses _Rreadk() 
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#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 


int main(void) 


{ 


_RFILE fp; 
RIOFB_T fb; 
char buf [4]; 


/* Create a physical file 

system("CRTPF FILE(QTEMP/MY_FILE)"); 

/* Open the file for write 

if ( (fp = _Ropen("QTEMP/MY FILE", “wr")) 


{ 


printf("open for write fails\n"); 


exit(1); 
} 


/* write some records into the file 


_Rwrite(fp, "KEY9", 
“Rwrite(fp, "KEY8", 
_Rwrite(fp, "KEY7", 
_Rwrite(fp, "KEY6", 
“Rwrite(fp, "KEY5", 
_Rwrite(fp, "KEY4", 
“Rwrite(fp, "KEY3", 
_Rwrite(fp, "KEY2", 
_Rwrite(fp, "KEY1", 
/* Close the file 
Rclose(fp); 


/* Open the file for read 
if ( (fp = _Ropen("QTEMP/MY_FILE", "rr")) 


{ 


printf("open for read fails\n"); 


exit (2); 
} 


/* Read the record with key KEY3 


4); 
4); 
4); 
4); 
4); 
4); 
4); 
4); 
4); 


*/ 


== NULL ) 


*/ 


== NULL ) 


fb = Rreadk(fp, buf, 4, __KEY_EQ, "KEY3", 4); 

printf("record %d with value %4.4s\n", fb->rrn, buf); 

/* Read the next record with key less than KEY3 */ 
fb = Rreadk(fp, buf, 4, _KEY_LT, "KEY3", 4); 

printf("record %d with value %4.4s\n", fb->rrn, buf); 

/* Read the next record with key greater than KEY3 x/ 
fb = Rreadk(fp, buf, 4, KEY GT, "KEY3", 4); 

printf("record %d with value %4.4s\n", fb->rrn, buf); 


/* Read the next record with different key 


fb = Rreadk(fp, buf, 4, __KEY_NEXTUNQ, "", 4); 
printf("record %d with value %4.4s\n", fb->rrn, buf); 


/* Close the file 
_Rclose(fp); 
} 


Related Information 
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_Rreadl() — Read the Last Record 
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Format 
#include <recio.h> 


_RIOFB_T *_Rread](_RFILE *fp, void *buf, size_t size, int opts); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The Rread1() function reads the last record in the access path currently being 
used for the file specified by fp. The access path may be keyed sequence or arrival 
sequence. Up to size number of bytes are copied from the record into buf (move 
mode only). The _Rread1() function locks the last record unless _ NO_LOCK is 
specified. 


The following parameters are valid for the _Rread1() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


opts Specifies the processing options for the file. Possible values are: 


__DFT 
If the file is opened for updating, then the record being read or 
positioned to is locked. The previously locked record will no 


longer be locked. 


__NO_LOCK 
Do not lock the record being positioned to. 


The Rread1() function is valid for database and DDM files. 
Return Value 


The _Rread1() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rread1() operation is successful the num_bytes field is set 
to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The key and rrn fields 
will be updated. If record blocking is taking place, the blk_count and blk_filled_by 
fields will be updated. If the file is empty, the num_bytes field is set to EOF. If it is 
unsuccessful, the num_bytes field is set to a value less than size and errno will be 
changed. 


The value of errno may be set to: 


Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 
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EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses Rread] () 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE «fp; 
_XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
} 


/* Get the library and file names of the file opened. */ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the last record. */ 
_Rread] ( fp, NULL, 20, _DFT ); 
printf ( "Last record: %10.10s\n", *(fp->in_buf) ); 


_Rclose ( fp ); 
} 


Related Information 


_Rreadn() — Read the Next Record 


Format 


#include <recio.h> 


_RIOFB_T *_Rreadn (_RFILE *fp, void *buf, size_t size, int opts); 


Language Level: ILE C Extension 
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Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreadn() function reads the next record in the access path that is currently 
being used for the file that is associated with fp. The access path may be keyed 
sequence or arrival sequence. Up to size number of bytes are copied from the 
record into buf (move mode only). The _Rreadn() function locks the record 
positioned to unless __ NO_LOCK is specified. 


If the file associated with fp is opened for sequential member processing and the 
current record position is the last record of any member in the file except the last, 
_Rreadn() will read the first record in the next member of the file. 


If an _Rlocate() operation positioned to a record specifying the __ PRIOR option, 
_Rreadn() will read the record positioned to by the _Rlocate() operation. 


If the file is open for record blocking and a call to _Rreadp() has filled the block, 
the _Rreadn() function is not valid if there are records remaining in the block. You 
can check the blk_count in _RIOFB_T to see if there are any remaining records. 


The following are valid parameters for the _Rreadn() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


opts Specifies the processing options for the file. Possible values are: 


__DFT 
If the file is opened for updating, then the record being read or 
positioned to is locked. The previously locked record will no 


longer be locked. 


__NO_LOCK 
Do not lock the record being positioned to. 


The _Rreadn() function is valid for all types of files except printer files. 
Return Value 


The _Rreadn() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rreadn() operation is successful the num_bytes field is 
set to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The key and rrn fields 
are updated. If the file that is associated with fp is a display file, the sysparm field 
is also updated. If record blocking is taking place, the blk_count and the 
blk_filled_by fields of the _RIOFB_T structure are updated. If attempts are made to 
read beyond the last record in the file, the num_bytes field is set to EOF If it is 
unsuccessful, the num_bytes field is set to a value less than size, and errno is 
changed. If you are using device files and specify zero as the size, check errno to 
determine if the function was successful. 


The value of errno may be set to: 


Value Meaning 
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ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses Rreadn() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE fp; 
“XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) 
{ 
printf ( "Open failed\n" ); 
exit (1); 
} 


/* Get the library and file names of the file opened. 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the first record. 
_Rreadf ( fp, NULL, 20, _ DFT ); 
printf ( "First record: %10.10s\n", *(fp->in_buf) ); 


/* Delete the second record. 


_Rreadn ( fp, NULL, 20, _DFT ); 
_Rdelete ( fp ); 


_Rclose ( fp ); 
} 


Related Information 
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_Rreadnc() — Read the Next Changed Record in a Subfile 


278 


Format 
#include <recio.h> 


_RIOFB_T * Rreadnc(_RFILE *fp, void *buf, size_t size); 
Language Level: ILE C Extension 

Thread Safe: NO. 

Description 


The _Rreadnc() function reads the next changed record from the current position 
in the subfile that is associated with fp. The minimum size of data that is read from 
the screen are copied from the system buffer to buf. 


The following are valid parameters for the _Rreadnc() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. 
The Rreadnc() function is valid for subfiles. 
Return Value 


The _Rreadnc() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rreadnc() operation is successful the num_bytes field is 
set to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The rrn and sysparm 
fields are updated. If there are no changed records between the current position 
and the end of the file, the num_bytes field is set to EOF. If it is unsuccessful, the 
num_bytes field is set to a value less than size, and errno is changed. 


The value of errno may be set to: 


Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455 for errno settings. 


Example that uses _Rreadnc() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 
#define LEN 10 
#define NUM_RECS 20 
#define SUBFILENAME "MYLIB/T1677RD6" 
#define PFILENAME "MYLIB/T1677RDB" 
typedef struct { 
char name[LEN] ; 
char phone[LEN]; 
} pf_t; 
#define RECLEN sizeof (pf_t) 
void init_subfile(_RFILE *, _RFILE *); 


int main(void) 


{ 


_RFILE «pf; 

_RFILE *subf; 

[RRR KKK A KKK KKK KKK KKK KKK IK KER AK KEK KK KEK AKER KKK 
* Open the subfile and the physical file. * 


KR KKK AK KKK KKK AKER K KEIR KEK KEKE KK KEI KEE KEKE ER | 
if ((pf = _Ropen(PFILENAME, "rr")) == NULL) { 
printf("can't open file %s\n", PFILENAME) ; 


exit(1); 

} 

if ((subf = Ropen(SUBFILENAME, "ar+")) == NULL) { 
printf("can't open file %s\n", SUBFILENAME) ; 
exit (2); 

} 

[RRR KKK AK KR A KKK A KKK KKK KKK IKKE RAK KKK KAA KER KKK 

* Initialize the subfile with records * 

* from the physical file. * 


FAK KK AK KKK KKK KKK KK KEI KKK KK KEK KK KKK KKK KERR EKER KK | 
init_subfile(pf, subf); 

[KERR KKK IKKE IKKE AK REAR K EK KK EKA K ERIK KAKA ARERR K 
* Write the subfile to the display by writing * 
* a record to the subfile control format. * 
KA KKK AK KKK KKK KKK KKK EA KKK AK KKK KKK AKER IKKE RARER KE | 
_Rformat(subf, "SFLCTL"); 

_Rwrite(subf, "", 0); 
_Rreadnc(subf, "", 0); 

[RRR KKK AK KR A KKK KKK KKK KKK IK KKK AK KKK KEK ER KKK 
* Close the physical file and the subfile. * 
FAK KK KKK KK KK KKK KK EA K KKK KKK KKK AKER AKER KEE KKK | 

_Rclose(pf); 

_Rclose(subf) ; 


Related Information 


_Rreadp() — Read the Previous Record 


Format 
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#include <recio.h> 


_RIOFB_T *_Rreadp(_RFILE *fp, void *buf, size_t size, int opts); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreadp() function reads the previous record in the access path that is 
currently being used for the file that is associated with fp. The access path may be 
keyed sequence or arrival sequence. Up to size number of bytes are copied from 
the record into buf (move mode only). The _Rreadp() function locks the record 
positioned to unless __ NO_LOCK is specified. 


If the file associated with fp is opened for sequential member processing and the 
current record position is the first record of any member in the file except the first, 
_Rreadp() will read the last record in the previous member of the file. 


If the file is open for record blocking and a call to _Rreadn() has filled the block, 
the _Rreadp() function is not valid if there are records remaining in the block. You 
can check the blk_count in _RIOFB_T to see if there are any remaining records. 


The following are valid parameters for the _Rreadp() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


opts Specifies the processing options for the file. Possible values are: 


__DFT 
If the file is opened for updating, then the record being read or 
positioned to is locked. The previously locked record will no 


longer be locked. 


__NO_LOCK 
Do not lock the record being positioned to. 


The _Rreadp() function is valid for database and DDM files. 
Return Value 


The _Rreadp() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rreadp() operation is successful the num_bytes field is 
set to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The key and rrn fields 
are also updated. If record blocking is taking place, the blk_count and the 
blk_filled_by fields of the _RIOFB_T structure are updated. If attempts are made to 
read prior to the first record in the file, the num_bytes field is set to EOF. If it is 
unsuccessful, the num_bytes field is set to a value less than size, and errno is 
changed. 


The value of errno may be set to: 
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Value Meaning 


ENOTREAD 
The file is not open for read operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses _Rreadp() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE xfps 
“XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. x/ 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
} 


/* Get the library and file names of the file opened. */ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the last record. «/ 
_Rread] ( fp, NULL, 20, _DFT ); 

printf ( "Last record: %10.10s\n", *(fp->in_buf) ); 

/* Get the previous record. */ 


_Rreadp ( fp, NULL, 20, _DFT ); 
printf ( "Next to last record: %10.10s\n", *(fp->in_buf) ); 


_Rclose ( fp ); 
} 


Related Information 
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_Rreads() — Read the Same Record 
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Format 
#include <recio.h> 


_RIOFB_T *_Rreads(_RFILE *fp, void *buf, size_t size, int opts); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rreads() function reads the current record in the access path that is currently 
being used for the file that is associated with fp. The access path may be keyed 
sequence or arrival sequence. Up to size number of bytes are copied from the 
record into buf (move mode only). The _Rreads() function locks the record 
positioned to unless __ NO_LOCK is specified. 


If the current position in the file that is associated with fp has no record associated 
with it, the Rreads() function will fail. 


The _Rreads() function is not valid when the file is open for record blocking. 


The following are valid parameters for the _Rreads() function. 


buf Points to the buffer where the data that is read is to be stored. If locate 
mode is used, this parameter must be set to NULL. 


size Specifies the number of bytes that are to be read and stored in buf. If locate 
mode is used, this parameter is ignored. 


opts Specifies the processing options for the file. Possible values are: 


__DFT 
If the file is opened for updating, then the record being read or 
positioned to is locked. The previously locked record will no 


longer be locked. 


__NO_LOCK 
Do not lock the record being positioned to. 


The _Rreads() function is valid for database and DDM files. 
Return Value 


The _Rreads() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rreads() operation is successful the num_bytes field is 
set to the number of bytes transferred from the system buffer to the user’s buffer 
(move mode) or the record length of the file (locate mode). The key and rrn fields 
are also updated. If it is unsuccessful, the num_bytes field is set to a value less 
than size, and errno is changed. 


The value of errno may be set to: 


Value Meaning 


ENOTREAD 
The file is not open for read operations. 
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ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and Hable 14 on page 455 for errno settings. 


Example that uses _Rreads() 


#include <stdlib.h> 
#include <recio.h> 


int main(void) 

{ 
_RFILE «fp; 
_XXOPFB_T — *opfb; 


/* Open the file for processing in arrival sequence. 
if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL 
{ 

printf ( "Open failed\n" ); 

exit (1); 


/* Get the library and file names of the file opened. 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the last record. 
_Rread] ( fp, NULL, 20, _ DFT ); 
printf ( "Last record: %10.10s\n", *(fp->in_buf) ); 


/* Get the same record without locking it. 
_Rreads ( fp, NULL, 20, __NO_LOCK); 
printf ( "Same record: %10.10s\n", *(fp->in_buf) ); 


_Rclose ( fp ); 
} 


Related Information 


) 


*/ 


_Rrelease() — Release a Program Device 


Format 
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#include <recio.h> 


int _Rrelease(_RFILE *fp, char dev); 
Language Level: ILE C Extension 
Thread Safe: NO. 

Description 


The Rrelease() function releases the program device that is specified by dev from 
the file that is associated with fp. The device name must be specified in uppercase. 


The dev parameter is a null-ended C string. 
The _Rrelease() function is valid for display and ICF files. 
Return Value 


The _Rrelease() function returns 1 if it is successful or zero if it is unsuccessful. 
The value of errno may be set to ELOERROR (a non-recoverable I/O error 


occurred) or ELORECERR (a recoverable I/O error occurred). See [able 12 onl 
bage 451] and for errno settings. 


Example that uses _Rrelease() 


#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 
typedef struct { 
char name[20] ; 
char address[25]; 
} formatl ; 
typedef struct { 
char name[8]; 
char password[10] ; 
} format2 ; 
typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


_RFILE *fp; /* File pointer x/ 

_RIOFB_T *rfb; /*Pointer to the file's feedback structure */ 

_XXIOFB_T *iofb; /* Pointer to the file's feedback area x/ 

formats buf, in_buf, out_buf; /* Buffers to hold data */ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", "“ar+" )) == NULL ) 
{ 


printf ( "Could not open file\n" ); 


exit (1); 
} 
_Racquire ( fp,"DEVICE1" ); /* Acquire another device. Replace */ 
/* with actual device name. */ 
_Rformat ( fp,"FORMAT1" ); /* Set the record format for the */ 
/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 


_Rpgmdev ( fp,"DEVICE2" ); /* Change the default program device. */ 
/* Replace with actual device name. */ 
_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 
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/* display file. */ 


rfb = _Rwrite ( fp, "", 0);  /* Set up the display. xf 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 


sizeof (out_buf )); 
_Rreadindv ( fp, &buf, sizeof(buf), DFT ); 
/* Read from the first device that */ 


/* enters data - device becomes */ 
/* default program device. */ 
/* Determine which terminal responded first. */ 


iofb = Riofbk ( fp ); 
if ( !strncmp ( "FORMAT! ", iofb -> rec_format, 10 )) 
{ 


} 


else 


{ 
} 


/* Continue processing. */ 
printf ( "Data displayed is %45.45s\n", &buf); 
_Rclose ( fp ); 


_Rrelease ( fp, "DEVICE1" ); 


_Rrelease(fp, "DEVICE2" ); 


} 


Related Information 


_Rrlsick() — Release a Record Lock 


Format 


#include <recio.h> 


int _Rrisick(_RFILE *fp); 
Language Level: ILE C Extension 
Description 


The _Rr1sick() function releases the lock on the currently locked record for the file 
specified by fp. The file must be open for update, and a record must be locked. If 
the _NO_POSITION option was specified on the _Rlocate() operation that locked 
the record, the record released may not be the record currently positioned to. 


The Rrlsick() function is valid for database and DDM files. 
Return Value 


The _Rr1sick() function returns 1 if the operation is successful, or zero if the 
operation is unsuccessful. 


The value of errno may be set to: 


Value Meaning 


ENOTUPD 
The file is not open for update operations. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 
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See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses _Rr1slck() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 


{ 


char buf [21]; 

_RFILE *fp; 

_XXOPFB_T = *opfb; 

int result; 

/* Open the file for processing in arrival sequence. x/ 


if (( fp = _Ropen ( "MYLIB/T1677RD1", "rr+, arrseq=Y" )) == NULL ) 
{ 

printf ( "Open failed\n" ); 

exit (1); 
}s 


/* Get the library and file names of the file opened. */ 
opfb = Ropnfbk ( fp ); 
printf ( "Library: %10.10s\nFile: %10.10s\n", 
opfb->library_name, 
opfb->file_name) ; 


/* Get the last record. */ 
_Rread] ( fp, NULL, 20, _DFT ); 
printf ( "Last record: %10.10s\n", *(fp->in_buf) ); 


/* _Rrlslck example. x/ 
result = Rrislck ( fp ); 
if ( result == 0 ) 

printf("_Rrlsick failed.\n"); 


_Rclose ( fp ); 
} 


Related Information 


_Rrollbck() — Roll Back Commitment Control Changes 


Format 
#include <recio.h> 


int _Rrollbck(void); 

Language Level: ILE C Extension 

Thread Safe: NO. 

Description 

The _Rrollbck() function reestablishes the last commitment boundary as the 
current commitment boundary. All changes that are made to the files under 


commitment control in the job, are reversed. All locked records are released. Any 
file that is open under commitment control in the job will be affected. You must 
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specify the keyword parameter commit=y when the file is opened to be under 


commitment control. A commitment control environment must have been set up 


prior to this. 
The Rrollbck() function is valid for database and DDM files. 
Return Value 


The _Rrollbck() function returns 1 if the operation is successful or zero if the 
operation is unsuccessful. The value of errno may be set to EIOERROR (a 


non-recoverable I/O error occurred) or EIORECERR (a _ recoverable I/O error 
occurred). See and for errno settings. 
Example that uses Rrol1bck() 


#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 
#include <string.h> 


int main(void) 

{ 
char buf [40]; 
int re = 1; 
_RFILE *purf 
_RFILE «dailyf; 


/* Open purchase display file and daily transaction file */ 
if ( ( purf = _Ropen ( "MYLIB/T1677RD3", "“art+,indicators=y" )) == NULL ) 
{ 
printf ( "Display file did not open.\n" ); 
exit (1); 
} 


if ( ( dailyf = _Ropen ( "MYLIB/T1677RDA", "wr,commit=y") ) == NULL ) 
{ 


printf ( "Daily transaction file did not open.\n" ); 
exit (2); 
} 


/* Select purchase record format */ 
_Rformat ( purf, "PURCHASE" ); 


/* Invite user to enter a purchase transaction. x*/ 
/* The _Rwrite function writes the purchase display. */ 
_Rwrite ( purf, "", 0); 

_Rreadn ( purf, buf, sizeof(buf), DFT ); 


/* Update daily transaction file x/ 
rc = (( _Rwrite ( dailyf, buf, sizeof(buf) ))->num_bytes ); 

/* If the databases were updated, then commit the transaction. */ 
/* Otherwise, rollback the transaction and indicate to the */ 
/* user that an error has occurred and end the application. x/ 
if (rc ) 


{ 


_Rcommit ( "Transaction complete" ); 


else 


{ 
_Rrollbck ( ); 
_Rformat ( purf, "ERROR" ); 
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_Rclose ( purf ); 
_Rclose ( dailyf ); 
} 


Related Information 


* Backup and Recovery manual 


_Rupdate() — Update a Record 


288 


Format 
#include <recio.h> 


_RIOFB_T *_Rupdate(_RFILE *fp, void xbuf, size_t size); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rupdate() function updates the record that is currently locked for update in 
the file that is specified by fp. The file must be open for update. A record is locked 
for update by reading or locating to it unless _ NO_LOCK is specified on the read 
or locate operation. If the _ NO_POSITION option is specified on a locate 
operation the record updated may not be the record currently positioned to. After 
the update operation, the updated record is no longer locked. 


The number of bytes that are copied from buf to the record is the minimum of size 
and the record length of the file (move mode only). If size is greater than the 
record length, the data is truncated, and errno is set to ETRUNC. One complete 
record is always written to the file. If the size is less than the record length of the 
file, the remaining data in the record will be the original data that was read into 
the system buffer by the read that locked the record. If a locate operation locked 
the record, the remaining data will be what was in the system input buffer prior to 
the locate. 


The _Rupdate() function can be used to update deleted records and key fields. A 
deleted record that is updated will no longer be marked as a deleted record. In 
both of these cases any keyed access paths defined for fp will be changed. 


Note: If locate mode is being used, Rupdate() works on the data in the file’s 
input buffer. 


The _Rupdate() function is valid for database, display (subfiles) and DDM files. 
Return Value 


The _Rupdate() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the _Rupdate() function is successful, the num_bytes field is set to the 
number of bytes transferred from the system buffer to the user’s buffer (move 
mode) or the record length of the file (locate mode). If fp is a display file, the 
sysparm field is updated. If the _Rupdate() function is unsuccessful, the 
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num_bytes field is set to a value less than the size specified (move mode) or zero 


(locate mode). The errno value will also be changed. 


The value of errno may be set to: 
Value Meaning 


ENOTUPD 
The file is not open for update operations. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455 for errno settings. 


Example that uses _Rupdate() 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 


int main(void) 
{ 
_RFILE = *in; 


char new_purchase[21] = "PEAR 1002022244"; 


/* Open the file for processing in keyed sequence. 


*/ 


if ( (in = _Ropen("MYLIB/T1677RD4", "rr+, arrseq=N")) == NULL ) 


printf("Open failed\n"); 
exit(1); 
}s 


/* Update the first record in the keyed sequence. 


_Rlocate(in, NULL, 0, _ FIRST); 
_Rupdate(in, new_purchase, 20); 


/* Force the end of data. 
_Rfeod(in); 


_Rclose(in); 


} 


Related Information 


*/ 


*/ 
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_Rupfb() — Provide Information on Last I/O Operation 


Format 
#include <recio.h> 


_RIOFB_T * Rupfb(_RFILE +fp); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rupfb() function updates the feedback structure associated with the file 
specified by fp with information about the last I/O operation. The _RIOFB_T 
structure will be updated even if riofb=N was specified when the file was opened. 
The num_bytes field of the _RIOFB_T structure will not be updated. See 

page 4 for a description of the _RIOFB_T structure. 


The _Rupfb() function is valid for all types of files. 


Return Value 


The _Rupfb() function returns _a pointer to the _RIOFB_T structure specified by fp. 
See Table 12.on page 45il and epee 


Example that uses _Rupfb() 


#include <stdio.h> 
#include <recio.h> 
#include <stdlib.h> 


int main(void) 


{ 


_RFILE  *fp3 

“RIOFB_T *fb; 

/* Create a physical file x/ 
system("CRTPF FILE(QTEMP/MY_FILE) RCDLEN(80)"); 

/* Open the file for write x/ 


if ( (fp = _Ropen("QTEMP/MY_FILE", "wr")) == NULL ) 
{ 
printf("open for write fails\n"); 
exit(1); 
} 
/* Write some records into the file */ 
_Rwrite(fp, "This is record 1", 16); 
_Rwrite(fp, "This is record 2", 16); 
_Rwrite(fp, "This is record 3", 16); 
_Rwrite(fp, "This is record 4", 16); 
_Rwrite(fp, "This is record 5", 16); 
_Rwrite(fp, "This is record 6", 16); 
_Rwrite(fp, "This is record 7", 16); 
_Rwrite(fp, "This is record 8", 16); 
Rwrite(fp, "This is record 9", 16); 


7* Close the file x/ 
_Rclose(fp); 
/* Open the file for read */ 


if ( (fp = _Ropen("QTEMP/MY_FILE", "rr, blkrcd = y")) == NULL ) 
{ 


printf("open for read fails\n"); 
exit(2); 
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} 

/* Read some records x/ 

_Rreadn(fp, NULL, 80, __DFT); 

_Rreadn(fp, NULL, 80, __DFT); 

/* Call _Rupfb and print feed back information x/ 

fb = _Rupfb(fp); 

printf("record number -------------------------- d\n", 
fb->rrn) ; 

printf("number of bytes read ------------------- %d\n", 
fb->num_bytes) ; 

printf("number of records remaining in block --- %hd\n", 
fb->blk_count) ; 

if ( fb->blk_filled_by == _ READ NEXT ) 

{ 


} 


else 


{ 


printf("block filled by ------------------------ __READ_NEXT\n"); 


printf (block filled by <sscc2ss2252-22---220-20 __READ_PREV\n") ; 
} 
/* Close the file */ 


_Rclose(fp); 
} 


Related Information 


_Rwrite() — Write the Next Record 


Format 


#include <recio.h> 


_RIOFB_T * _Rwrite(_RFILE *fp, void *buf, size_t size); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 


The _Rwrite() function has two modes: move and locate. When buf points to a 
user buffer, Rwrite() is in move mode. When buf is NULL, the function is in 
locate mode. 


The _Rwrite() function appends a record to the file specified by fp. The number of 
bytes copied from buf to the record is the minimum of size and the record length of 
the file (move mode only). If size is greater than the record length, the data is 
truncated and errno is set to ETRUNC. One complete record is always written if 
the operation is successful. 


If you are using Ropen() and then _Rwrite() to output records to a source 
physical file, the sequence numbers must be manually appended. 


The _Rwrite() function has no effect on the position of the file for a subsequent 
read operation. 


If record blocking is taking place and the file associated with fp is nearing the limit 
of the number of records it can contain, records may be lost although the 
_Rwrite() function indicates success. This can happen if another file pointer is 
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being used to write records to the file and it fills the file before the records in the 
block are written to the file. In this case, the _Rwrite() function will indicate an 
error has occurred only on the call to the _Rwrite() function that sends the data to 
the database. 


The _Rwrite() function is valid for all types of files. 
Return Value 


The _Rwrite() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rwrite() operation is successful the num_bytes field is 
set to the number of bytes written for both move mode and locate mode. The 
function transfers the bytes from the user’s buffer to the system buffer. If record 
blocking is taking place, the function only updates the rrn and key fields when it 
sends the block to the database. If fp is a display, ICF or printer file, the function 
updates the sysparm field. If it is unsuccessful, the num_bytes field is set to a 
value less than size specified (move mode) or zero (locate mode) and errno is 
changed. 


The value of errno may be set to: 
Value Meaning 


ENOTWRITE 
The file is not open for write operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rwrite() 


#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 
typedef struct { 
char name[20] ; 
char address[25]; 
} formatl ; 
typedef struct { 
char name[8]; 
char password[10] ; 
} format2 ; 
typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


{ 


_RFILE fp; /* File pointer x/ 

_RIOFB_T *rfb; /*Pointer to the file's feedback structure x/ 

_XXIOFB_T *iofb; /* Pointer to the file's feedback area x/ 

formats buf, in_buf, out_buf; /* Buffers to hold data */ 
/* Open the device file. */ 
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if (( fp = _Ropen ( "MYLIB/T1677RD2", “ar+" )) == NULL ) 
{ 
printf ( "Could not open file\n" ); 


exit (1); 
_Racquire ( fp,"DEVICE1" ); /* Acquire another device. Replace */ 
/* with actual device name. */ 
_Rformat ( fp,"FORMAT1" ); /* Set the record format for the «/ 
/* display file. x/ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 


_Rpgmdev ( fp,"DEVICE2" ); /* Change the default program device. */ 
/* Replace with actual device name. */ 
_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = Rwrite ( fp, "", 0);  /* Set up the display. */ 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 


sizeof (out_buf )); 
_Rreadindv ( fp, &buf, sizeof(buf), DFT ); 
/* Read from the first device that */ 


/* enters data - device becomes */ 
/* default program device. */ 
/* Determine which terminal responded first. x*/ 


iofb = Riofbk ( fp ); 
if ( !strncmp ( "FORMAT1 ", iofb -> rec_format, 10 )) 
{ 


} 


else 


{ 
} 


/* Continue processing. */ 
printf ( "Data displayed is %45.45s\n", &buf); 
_Rclose ( fp ); 


_Rrelease ( fp, "DEVICE1" ); 


_Rrelease(fp, "DEVICE2" ); 


Related Information 


_Rwrited() — Write a Record Directly 


Format 
#include <recio.h> 


_RIOFB_T *_Rwrited(_RFILE *fp, void *buf, size_t size, unsigned long rrn); 
Language Level: ILE C Extension 


Thread Safe: YES. However, if the file pointer is passed among threads, the I/O 
feedback area is shared among those threads. 


Description 
The _Rwrited() function writes a record to the file associated with fp at the 
position specified by rrn. The _Rwrited() function will only write over deleted 


records. The number of bytes copied from buf to the record is the minimum of size 
and the record length of the file (move mode only). If size is greater than the 
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record length, the data is truncated, and errno is set to ETRUNC. One complete 
record is always written if the operation is successful. 


The _Rwrited() function has no effect on the position of the file for a read 
operation. 


The Rwrited() function is valid for database, DDM and subfiles. 
Return Value 


The _Rwrited() function returns a pointer to the _RIOFB_T structure associated 
with fp. If the _Rwrited() operation is successful the num_bytes field is set to the 
number of bytes transferred from the user’s buffer to the system buffer (move 
mode) or the record length of the file (locate mode). The rrn field is updated. If fp 
is a display file, the sysparm field is updated. If it is unsuccessful, the num_bytes 
field is set to a value less than size specified (move mode) or zero (locate mode) 
and errno is changed. 


The value of errno may be set to: 


Value Meaning 


ENOTWRITE 
The file is not open for write operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rwrited() 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <stdlib.h> 
#include <recio.h> 
#define LEN 10 
#define NUM_RECS 20 
#define SUBFILENAME "MYLIB/T1677RD6" 
#define PFILENAME "MYLIB/T1677RDB" 
typedef struct { 
char name[LEN] ; 
char phone[LEN]; 
} pf_t; 
#define RECLEN sizeof (pf_t) 
void init_subfile(_RFILE *, _RFILE *); 
int main(void) 


{ 


_RFILE «pf; 
_RFILE *subf; 
/* Open the subfile and the physical file. */ 


if ((pf = _Ropen(PFILENAME, "rr")) == NULL) { 
printf("can't open file %s\n", PFILENAME) ; 


exit(1); 
} 
if ((subf = _Ropen(SUBFILENAME, "ar+")) == NULL) { 
printf("can't open file %s\n", SUBFILENAME) ; 
exit (2); 
} 
/* Initialize the subfile with records * 
* from the physical file. x/ 


init_subfile(pf, subf); 
/* Write the subfile to the display by writing * 
* a record to the subfile control format. */ 
_Rformat(subf, "SFLCTL"); 
_Rwrite(subf, "", 0); 
_Rreadnc(subf, "", 0); 


/* Close the physical file and the subfile. */ 
_Rclose(pf); 
_Rclose(subf) ; 
} 
void init_subfile(_RFILE *pf, _RFILE *subf) 
{ 
_RIOFB_T *fb; 
int ‘lis 
pf_t record; 
/* Select the subfile record format. */ 


_Rformat(subf, "SFL"); 
for (i = 1; i <= NUMRECS; i++) { 
fb = Rreadn(pf, &record, RECLEN, DFT); 
if (fb->num_bytes != RECLEN) { 
printf("%d\n", fb->num_bytes) ; 
printf("%d\n", RECLEN); 
printf("error occurred during read\n"); 
exit(3); 


} 
fb = Rwrited(subf, &record, RECLEN, i); 
if (fb->num_bytes != RECLEN) { 


printf("error occurred during write\n"); 
exit(4); 


} 


Related Information 
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Format 


#include <recio.h> 
_RIOFB_T *_Rwriterd(_RFILE «fp, void *buf, size_t size); 


Language Level: ILE C Extension 
Thread Safe: NO. 
Description 


The _Rwriterd() function performs a write and then a read operation on the file 
that is specified by fp. The minimum of size and the length of the current record 
format determines the amount of data to be copied between the system buffer and 
buf for both the write and read parts of the operation. If size is greater than the 
record length of the current format, errno is set to ETRUNC on the write part of 
the operation. If size is less than the length of the current record format, errno is set 
to ETRUNC on the read part of the operation. 


The _Rwriterd() function is valid for display and ICF files. 
Return Value 


The _Rwriterd() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rwriterd() operation is successful, the num_bytes field 
is set to the number of bytes transferred from the system buffer to buf on the read 
part of the operation (move mode) or the record length of the file (locate mode). 


The value of errno may be set to: 


Value Meaning 


ENOTUPD 
The file is not open for update operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [able 14 on page 455] for errno settings. 


Example that uses Rwriterd() 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 


typedef struct { 
char name[20]; 
char address[25]; 
} formatl ; 


typedef struct { 

char name[8]; 

char password[10]; 
} format2 ; 


typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


{ 


_RFILE fp; /* File pointer */ 
_RIOFB_T *rfb; /*Pointer to the file's feedback structure */ 
formats buf, in_buf, out_buf; /* Buffers to hold data x*/ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", “ar+" )) == NULL ) 
{ 

printf ( "Could not open file\n" ); 

exit (1); 
} 


_Rpgmdev ( fp,"DEVICE2" );/* Change the default program device. */ 
/* Replace with actual device name. */ 


_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = _Rwrite ( fp, "", 0);  /* Set up the display. xi 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 
sizeof (out_buf )); 
/* Continue processing. */ 


_Rclose ( fp ); 
} 


Related Information 


_Rwrread() — Write and Read a Record (separate buffers) 


Format 


#include <recio.h> 


_RIOFB_T *_Rwrread(_RFILE *fp, void *in_buf, size_t in_buf_size, 
void *out_buf, size_t out_buf_size); 
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Language Level: ILE C Extension 
Thread Safe: NO. 
Description 


The _Rwrread() function performs a write and then a read operation on the file 
that is specified by fp. Separate buffers may be specified for the input and output 
data. The minimum of size and the length of the current record format determines 
the amount of data to be copied between the system buffer and the buffers for 
both the write and read parts of the operation. If out_buf_size is greater than the 
record length of the current format, errno is set to ETRUNC on the write part of 
the operation. If in_buf_size is less than the length of the current record format, 
errno is set to ETRUNC on the read part of the operation. 


The _Rwrread() function is valid for display and ICF files. 
Return Value 


The _Rwrread() function returns a pointer to the _RIOFB_T structure that is 
associated with fp. If the _Rwrread() operation is successful, the num_bytes field is 
set to the number of bytes transferred from the system buffer to in_buf in the read 
part of the operation (move mode) or the record length of the file (locate mode). 


The value of errno may be set to: 


Value Meaning 


ENOTUPD 
The file is not open for update operations. 


ETRUNC 
Truncation occurred on an I/O operation. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


See [able 12 on page 451] and [Table 14 on page 455] for errno settings. 


Example that uses Rwrread() 
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#include <stdio.h> 
#include <recio.h> 
#include <string.h> 
#include <stdlib.h> 


typedef struct { 
char name[20]; 
char address[25]; 
} formatl ; 


typedef struct { 

char name[8]; 

char password[10]; 
} format2 ; 


typedef union { 
formatl fmt1; 
format2 fmt2; 
} formats ; 


int main(void) 


{ 


_RFILE fp; /* File pointer */ 
_RIOFB_T *rfb; /*Pointer to the file's feedback structure */ 
formats buf, in_buf, out_buf; /* Buffers to hold data x*/ 
/* Open the device file. */ 


if (( fp = _Ropen ( "MYLIB/T1677RD2", "“ar+" )) == NULL ) 
{ 
printf ( "Could not open file\n" ); 


exit (1); 
} 


_Rpgmdev ( fp,"DEVICE2" );/* Change the default program device.  */ 
/* Replace with actual device name. */ 


_Rformat ( fp,"FORMAT2" );  /* Set the record format for the */ 


/* display file. */ 
rfb = _Rwrite ( fp, "", 0);  /* Set up the display. xi 
rfb = Rwriterd ( fp, &buf, sizeof(buf) ); 
rfb = Rwrread ( fp, &in_buf, sizeof(in_buf), &out_buf, 
sizeof (out_buf )); 
/* Continue processing. */ 


_Rclose ( fp ); 
} 


Related Information 


scanf() — Read Data 


Format 
#include <stdio.h> 
int scanf(const char *format-string, argument-list); 


Language Level: ANSI 
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Description 


The scanf() function reads data from the standard input stream stdin into the 
locations that is given by each entry in argument-list. Each argument must be a 
pointer to a variable with a type that corresponds to a type specifier in 
format-string. The format-string controls the interpretation of the input fields, and is 
a multibyte character string that begins and ends in its initial shift state. 


The format-string can contain one or more of the following: 


* White-space characters, as specified by the isspace() functionl (such as blanks 


and new-line characters). A white-space character causes the scanf() function to 
read, but not to store, all consecutive white-space characters in the input up to 
the next character that is not white space. One white-space character in 
format-string matches any combination of white-space characters in the input. 


* Characters that are not white space, except for the percent sign character (%). A 
non-whitespace character causes the scanf() function to read, but not to store, a 
matching non-whitespace character. If the next character in stdin does not 
match, the scanf() function ends. 


* Format specifications, introduced by the percent sign (%). A format specification 
causes the scanf() function to read and convert characters in the input into 
values of a specified type. The value is assigned to an argument in the argument 
list. 


The scanf() function reads format-string from left to right. Characters outside of 
format specifications are expected to match the sequence of characters in stdin; the 
matched characters in stdin are scanned but not stored. If a character in stdin 
conflicts with format-string, scanf() ends. The conflicting character is left in stdin 
as if it had not been read. 


When the first format specification is found, the value of the first input field is 
converted according to the format specification and stored in the location specified 
by the first entry in argument-list. The second format specification converts the 
second input field and stores it in the second entry in argument-list, and so on 
through the end of format-string. 


An input field is defined as all characters up to the first white-space character 
(space, tab, or new line), up to the first character that cannot be converted 
according to the format specification, or until the field width is reached, whichever 
comes first. If there are too many arguments for the format specifications, the extra 
arguments are ignored. The results are undefined if there are not enough 
arguments for the format specifications. 


A format specification has the following form: 


pp —% type >< 


* | width | -— precision | 


ss r > 


Each field of the format specification is a single character or a number signifying a 
particular format option. The type character, which appears after the last optional 
format field, determines whether the input field is interpreted as a character, a 
string, or a number. The simplest format specification contains only the percent 
sign and a type character (for example, %s). 
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Each field of the format specification is discussed in detail below. If a percent sign 
(%) is followed by a character that has no meaning as a format control character, 
that character and following characters up to the next percent sign are treated as 
an ordinary sequence of characters; that is, a sequence of characters that must 
match the input. For example, to specify a percent-sign character, use %%. 


The following restrictions apply to pointer printing and scanning: 


* Ifa pointer is printed out and scanned back from the same activation group, the 
scanned back pointer will be compared equal to the pointer that is printed out. 


* Ifa scanf() family function scans a pointer that was printed out by a different 
activation group, the scanf() family function will set the pointer to NULL. 


See the WebSphere Development Studio: ILE C/C++ Programmer’s Guide for more 
information about using iSeries pointers. 


An asterisk (*) following the percent sign suppresses assignment of the next input 
field, which is interpreted as a field of the specified type. The field is scanned but 
not stored. 


The width is a positive decimal integer controlling the maximum number of 
characters to be read from stdin. No more than width characters are converted and 
stored at the corresponding argument. Fewer than width characters are read if a 
white-space character (space, tab, or new line), or a character that cannot be 
converted according to the given format occurs before width is reached. 


The optional size modifiers h, |, ll, and L indicate the size of the receiving object. 
The conversion characters d, i, and n must be preceded by h if the corresponding 
argument is a pointer to short int rather than a pointer to int, by | if it is a pointer 
to long int, or by ll if it is a pointer to long long int. Similarly, the conversion 
characters 0, u, x, and X must be preceded by h if the corresponding argument is a 
pointer to unsigned short int rather than a pointer to unsigned int, by | if it is a 
pointer to unsigned long int, or by Il if it is a pointer to unsigned long long int. 
The conversion characters e, E, f, g, and G must be preceded by 1 if the 
corresponding argument is a pointer to double rather than a pointer to float, or by 
Lif it is a pointer to a long double. Finally, the conversion characters c, s, and [ 
must be preceded by | if the corresponding argument is a pointer to wchar_t rather 
than a pointer to a single byte character type. If an h, 1, L or ll appears with any 
other conversion character, the behavior is undefined. 


The type characters and their meanings are in the following table: 


Character | Type of Input Expected Type of Argument 

d Signed decimal integer Pointer to int. 

fe) Unsigned octal integer Pointer to unsigned int. 
x, X Unsigned hexadecimal integer Pointer to unsigned int. 
i Decimal, hexadecimal, or octal integer | Pointer to int. 

u Unsigned decimal integer Pointer to unsigned int. 


e, f, g, E, | Floating-point value consisting of an Pointer to float. 
G optional sign (+ or -); a series of one or 
more decimal digits possibly 
containing a decimal point; and an 
optional exponent (e or E) followed by 
a possibly signed integer value. 
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Character | Type of Input Expected Type of Argument 


D(n,p) Packed decimal value consisting of an | Pointer to decimal(n,p). Since the 
optional sign (+ or -); then a internal representation of the binary 
non-empty sequence of digits, coded decimal object is the same as the 
optionally a series of one or more internal representation of the packed 
decimal digits possibly containing a decimal data type, you can use the 


decimal point, but not a decimal suffix. | type character D(n,p). 
The subject sequence is defined as the 
longest initial subsequence of the input 
string, starting with the first 
non-whitespace character, in the 
expected form. It contains no 
characters if the input string is empty 
or consists entirely of white space, or if 
the first non-whitespace character is 
anything other than a sign, a digit, or a 
decimal point character. 


Cc Character; white-space characters that | Pointer to char large enough for input 
are ordinarily skipped are read when c | field. 
is specified 


Ss String Pointer to character array large enough 
for input field plus a ending null 
character (\0), which is automatically 
appended. 


n No input read from stream or buffer Pointer to int, into which is stored the 
number of characters successfully read 
from the stream or buffer up to that 
point in the call to scanf(). 


p Pointer to void converted to series of | Pointer to void. 
characters 

Ic Multibyte character constant Pointer to wchar_t. 

ls Multibyte string constant Pointer to wchar_t string. 


To read strings not delimited by space characters, substitute a set of characters in 
brackets ([ ]) for the s (string) type character. The corresponding input field is read 
up to the first character that does not appear in the bracketed character set. If the 
first character in the set is a caret ( ), the effect is reversed: the input field is read 
up to the first character that does appear in the rest of the character set. 


To store a string without storing an ending null character (\0), use the specification 
Yoac, where a is a decimal integer. In this instance, the c type character means that 
the argument is a pointer to a character array. The next a characters are read from 
the input stream into the specified location, and no null character is added. 


The input for a %x format specifier is interpreted as a hexadecimal number. 


The scanf() function scans each input field character by character. It might stop 
reading a particular input field either before it reaches a space character, when the 
specified width is reached, or when the next character cannot be converted as 
specified. When a conflict occurs between the specification and the input character, 
the next input field begins at the first unread character. The conflicting character, if 
there was one, is considered unread and is the first character of the next input field 
or the first character in subsequent read operations on stdin. 
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For %lc and “%ls, specifies the data that is read is a multibyte string and is 
converted to wide characters as if by calls to mbtowc. Unless stdin has been 
overridden, the data is assumed to be in the CCSID of the job, and is converted to 
either wide EBCDIC, or if the source is compiled with 
LOCALETYPE(**LOCALEUCS2), into UNICODE. 


Alternative format specification has the following form: 


>>—%—arg-number$ 


type >< 


* | width | . precision | 


ss r> 


As an alternative, specific entries in the argument-list may be assigned by using 
the format specification outlined in the diagram above. This format specification 
and the previous format specification may not be mixed in the same call to 
scanf(). Otherwise, unpredictable results may occur. 


The arg-number is a positive integer constant where 1 refers to the first entry in 
the argument-list. Arg-number may not be greater than the number of entries in 
the argument-list, or else the results are undefined. Arg-number also may not be 
greater than NL_LARGMAX. 


Return Value 
The scanf() function returns the number of fields that were successfully converted 
and assigned. The return value does not include fields that were read but not 


assigned. 


The return value is EOF for an attempt to read at end-of-file if no conversion was 
performed. A return value of 0 means that no fields were assigned. 


Error Conditions 

If the type of the argument that is to be assigned into is different than the format 
specification, unpredictable results can occur. For example, reading a floating point 
value, but assigning it into a variable of type int, is incorrect and would have 
unpredictable results. 

If there are more arguments than format specifications, the extra arguments are 
ignored. The results are undefined if there are not enough arguments for the 


format specifications. 


If the format string contains an invalid format specification, and positional format 
specifications are being used, errno will be set to EILSEQ. 


If positional format specifications are used and there are not enough arguments, 
errno will be set to EINVAL. 


Examples using scanf () 


This example scans various types of data. 
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#include <stdio.h> 


int main(void) 
{ 
int is; 
float fp; 
char c, s[81]; 


printf("Enter an integer, a real number, a character " 
"and a string : \n"); 

if (scanf("%d %f %c %s", &i, &fp, &c, s) != 4) 
printf("Not all fields were assigned\n"); 

else 

{ 
printf("integer = %d\n", i); 
printf("real number = %f\n", fp); 
printf("character = %c\n", c); 
printf("string = %s\n",s); 

} 

} 


[KEKKRKKKRKKEKKKEKRK LF input 1S: 12 2.5 A YOS,  *AKKKKKKKKKKEKKKKKE 
KKKKKKKKKKKERK then output Should be similar tO: ****KKKKKKKKKKKK 


Enter an integer, a real number, a character and a string : 
integer = 12 

real number = 2.500000 

character = a 

string = yes 

x/ 


This example converts a hexadecimal integer to a decimal integer. The while loop 
ends if the input value is not a hexadecimal integer. 


#include <stdio.h> 
int main(void) 
int number; 


printf("Enter a hexadecimal number or anything else to quit:\n"); 
while (scanf("%x", &number) ) 
{ 
printf ("Hexadecimal Number 
printf("Decimal Number 


} 


%x\n",number) ; 
%d\n",number) ; 


} 


[KeKKKKKKKKKKKKK TF input is: 0x231 Oxf5e Oxl ,  KXRKKKKKKKKKKK ** 
KRKKKKKKEKKKKRKRK then output should be similar to: ****k**kk*kKKEKK 


Enter a hexadecimal number or anything else to quit: 


Hexadecimal Number = 231 
Decimal Number = 561 
Hexadecimal Number = f5e 
Decimal Number = 3934 
Hexadecimal Number = 1 
Decimal Number = 1 


*/ 


This example reads from stdin and assigns data by using the alternative positional 
format string. 
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#include <stdio.h> 

int main(int argc, char *argv[]) 
{ 

int i; 

char s[20]; 

float f; 


scanf("%2$s %3$f %1$d",&i, s, &f); 
printf("The data read was %i\n%s\n%f\n,i,s,f); 


return 0; 


} 


/* If the input is : test 0.2 100 
then the output will be similar to: */ 
The data read was 

100 

test 

0.20000 


This example reads in a multibyte character string into a wide UNICODE string. 
Compile with LOCALETYPE(*LOCALEUCS2) 


#include <locale.h> 
#include <stdio.h> 
#include <wchar.h> 


void main(void) 
{ 
wchar_t uString[20]; 


setlocale(LC_UCS2_ALL, ""); 
scanf("Enter a string %ls",uString); 


printf("String read was %1s\n",uString) ; 


} 


/* if the input is : ABC 
then the output will be similiar to: 


String read was ABC 
*/ 


Related Information 


setbuf() — Control Buffering 


Format 
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#include <stdio.h> 
void setbuf(FILE *, char buffer); 


Language Level: ANSI 
Description 


If the operating system supports user-defined buffers, setbuf() controls buffering 
for the specified stream. The setbuf() function only works in ILE C when using the 
integrated file system. The stream pointer must refer to an open file before any I/O 
or repositioning has been done. 


If the buffer argument is NULL, the stream is unbuffered. If not, the buffer must 
point to a character array of length BUFSIZ, which is the buffer size that is defined 
in the <stdio.h> include file. The system uses the buffer, which you specify, for 
input/output buffering instead of the default system-allocated buffer for the given 
stream. stdout, stderr, and stdin do not support user-defined buffers. 


The setvbuf() function is more flexible than the setbuf() function. 


Note: Under ILE C, streams are fully buffered by default, with the exceptions of 
the stderr function, which is line-buffered, and memory files, which are 
unbuffered. 


Return Value 
There is no return value. 
Example that uses setbuf () 


This example opens the file setbuf.dat for writing. It then calls the setbuf () 
function to establish a buffer of length BUFSIZ. When string is written to the 
stream, the buffer buf is used and contains the string before it is flushed to the file. 


#include <stdio.h> 
int main(void) 
char buf[BUFSIZ]; 
char string[] = "hello world"; 
FILE «stream; 
memset (buf,'\@',BUFSIZ); /* initialize buf to null characters */ 
stream = fopen("setbuf.dat", "wb"); 


setbuf (stream, buf); /* set up buffer */ 


fwrite(string, sizeof(string), 1, stream); 


printf ("%s\n", buf) ; /* string is found in buf now */ 
fclose(stream) ; /* buffer is flushed out to myfile.dat */ 


} 


Related Information 
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setjmp() — Preserve Environment 


Format 


#include <setjmp.h> 
int setjmp(jmp_buf env); 


Language Level: ANSI 
Description 


The setjmp() function saves a stack environment that can subsequently be restored 
by the longjmp() function. The setjmp() and longjmp() functions provide a way to 
perform a non-local goto. They are often used in signal handlers. 


A call to the setjmp() function causes it to save the current stack environment in 
env. A subsequent call to the longjmp() function restores the saved environment 
and returns control to a point corresponding to the setjmp() call. The values of all 
variables (except register variables) accessible to the function receiving control 
contain the values they had when the longj mp() function was called. The values of 
register variables are unpredictable. Nonvolatile auto variables that are changed 
between calls to the setjmp() function and the longjmp() function are also 
unpredictable. 


Return Value 


The setjmp() function returns the value 0 after saving the stack environment. If the 
setjmp() function returns as a result of a longjmp() call, it returns the value 
argument of the longjmp() function, or 1 if the value argument of the longjmp() 
function is 0. There is no error return value. 


Example that uses set jmp() 
This example stores the stack environment at the statement if(setjmp(mark) != 0) ... 


When the system first performs the if statement, it saves the environment in mark 
and sets the condition to FALSE because setjmp()returns a 0 when it saves the 
environment. The program prints the message: 


setjmp has been called 


The subsequent call to function p tests for a local error condition, which can cause 
it to perform the longjmp() function. Then, control returns to the original function 
using the environment that is saved in mark. This time, the condition is TRUE 
because -1 is the return value from the longjmp() function. The program then 
performs the statements in the block and prints: 


setjmp has been called 
Then the program calls the recover() function and exits. 


#include <stdio.h> 
#include <setjmp.h> 


jmp_buf mark; 
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void p(void); 
void recover(void); 


int main(void) 


if (setjmp(mark) != 0) 

{ 
printf("longjmp has been called\n"); 
recover(); 


printf("setjmp has been called\n"); 
pQ)s 
exit(1); 

} 


void p(void) 
{ 


longjmp(mark, -1); 
} 


void recover(void) 


{ 
exit(1); 
} 


Related Information 


setlocale() — Set Locale 
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Format 

#include <locale.h> 

char *setlocale(int category, const char *locale); 

Language Level: ANSI 

Thread Safe: NO. 

Description 

The setlocale() function changes or queries variables that are defined in the 


<locale.h> include file, that indicate location. The values for category are listed 
below. 


Category Purpose 

LC_ALL Names entire locale of program. 

LC_COLLATE Affects behavior of the strcol1() and strxfrm() functions. 

LC_CTYPE Affects behavior of character handling functions. 

LC_MONETARY Affects monetary information returned by localeconv() and 
nl_langinfo() functions. 

LC_NUMERIC Affects the decimal-point character for the formatted 
input/output and string conversion function, and the 
non-monetary formatting information returned by the 
localeconv() and nl_langinfo() functions. 
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Category Purpose 


LC_TIME Affects behavior of the strftime() function and the time 
formatting information returned by the nl_langinfo() function. 
LC_UCS2_ALL* This category causes setlocale() to load the LC_*, 


LC_UCS2_CTYPE and the LC_UCS2_COLLATE categories from 
the locale specified. This category only accepts a locale with a 
UCS2 CCSID. LC_UCS2_ALL is identical to LC_ALL in 
function when LOCALETYPE(*LOCALEUCS2) is used. 


LC_UCS2_CTYPE* This category causes the UCS2 CTYPE information to be set 
from the specified locale. The locale must have a UCS2 CCSID. 


LC_UCS2_COLLATE* This category causes the UCS2 Collating sequence information 
to be set from the specified locale. The locale must have a 
UCS2 CCSID. 
Note: This category is not supported. 


LC_TOD Affects the behavior of the time functions. 


The category LC_TOD has several fields in it. The TNAME 
field is the time zone name. The TZDIFF field is the difference 
between local time and Greenwich Meridian time. If the 
TNAME field is nonblank, then the TZDIFF field is used when 
determining the values that are returned by some of the time 
functions. This value takes precedence over the system value, 
QUTCOFFSET. 


LC_MESSAGES Affects the behavior of the catclose(), catgets()and 
catopen()functions and the message formatting information 
returned by the nl_langinfo() function. 


i For categories with UCS2 in the name, and for crtcmod or crtbndc, the option is 
LOCALETYPE(*LOCALEUCS2). 


Note: There are two ways of defining setlocale() and other locale-sensitive C 
functions on the iSeries server. The original way to define setlocale() uses 
*CLD locale objects to set the locale and retrieve locale-sensitive data. The 
second way to define setlocale() uses *LOCALE objects to set the locale 
and retrieve locale-sensitive data. The original way is accessed by specifying 
LOCALETYPE(*CLD) on the compilation command. The second way is 
accessed by specifying LOCALETYPE(*LOCALE) on the compilation 
command. For more information on the two methods of locale definition in 
ILE C, see "International Locale Support” in the WebSphere Development 
Studio: ILE C/C++ Programmer's Guide. 


Setlocale using *CLD locale objects 


You can set the value of locale to "C", "", LC_C, LC_C_ GERMANY, LC_C_FRANCE, 
LC_C_SPAIN, LC_C_ITALY, LC_C_USA or LC_C_UK. A locale value of "C" 
indicates the default C environment. A locale value of "" tells the 

setlocale() function to use the default locale for the implementation. 


Setlocale with *LOCALE objects. 
You can set the value of locale to "", "C", "POSIX" or the fully qualified Integrated 
File System path name of a *LOCALE object enclosed in double quotes. A locale 


value of "C" or "POSIX" indicates the default C *LOCALE object. A locale value of 
"" tells the setlocale() function to use the default locale for the process. 
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If compiled with LOCALETYPE(*LOCALEUCS2), the locale must be a pointer to a 
valid UNICODE locale for the categories starting with LC_UCS2, and must not be 
a UNICODE locale for the other categories. 


Return Value 


The setlocale() function returns a pointer to a string that, if passed back to the 
setlocale() function, would restore the locale to the previous setting. This string 
should be copied by the user as it will be overwritten on subsequent calls to 
setlocale(). 


Note: Because the string to which a successful call to setlocale() points may be 
overwritten by subsequent calls to the setlocale() function, you should 
copy the string if you plan to use it later. The exact format of the locale 
string is different between locale types of *CLD, *LOCALE and 
*LOCALEUCS2. 


To query the locale, give a NULL as the second parameter. For example, to query 
all the categories of your locale, enter the following statement: 


char *string = setlocale(LC_ALL, NULL); 
Error Conditions 


On error, the setlocale() function returns NULL, and the program’s locale is not 
changed. 


Example that uses *CLD locale objects 


[RRR KKK A KERIKERI KKK KKK KKK IK KKK IKK AK KAKA KKK KKK A KEK KKK AKER KK 


This example sets the locale of the program to 

LC_C_FRANCE *CLD and prints the string 

that is associated with the locale. This example must be compiled with 
the LOCALETYPE(*CLD) parameter on the compilation command. 


* 
KR KKK A KKK KKK AK KKK KKK KK KKK KKK KKK IKK KKK KIRK KKK KKK AK KIA KKK AK ERK K EE | 


#include <stdio.h> 
#include <locale.h> 


char «string; 


int main(void) 
{ 
string = setlocale(LC_ALL, LC_C_FRANCE); 
if (string != NULL) 
printf(" %s \n",string); 
} 


Example that uses *LOCALE objects 
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[RRR KKK KK EAR KEIR KARR KKK KEK KK KKK AK KKK A KK KIKI AK KEK KEK A KARE 


This example sets the locale of the program to be "POSIX" and prints 
the string that is associated with the locale. This example must be 
compiled with the LOCALETYPE(*LOCALE) parameter on the CRTCMOD or 
CRTBNDC command. 


KR KKK A KKK A KKK KKK KKK KKK KKK IKK KKK KKK EI KKK KKK A KEK AKER AKER KEKE | 


#include <stdio.h> 
#include <locale.h> 


char «string; 


int main(void) 


{ 
string = setlocale(LC_ALL, "POSIX"); 
if (string != NULL) 
printf(" %s \n",string); 
} 


Related Information 


setvbuf() — Control Buffering 


Format 


#include <stdio.h> 
int setvbuf(FILE *stream, char *buf, int type, size_t size); 


Language Level: ANSI 
Thread Safe: YES. 
Description 


The setvbuf() function allows control over the buffering strategy and buffer size 
for a specified stream. The setvbuf() function only works in ILE C when using the 
integrated file system. The stream must refer to a file that has been opened, but 
not read or written to. 


The array pointed to by buf designates an area that you provide that the C library 
may choose to use as a buffer for the stream. A buf value of NULL indicates that 
no such area is supplied and that the C library is to assume responsibility for 
managing its own buffers for the stream. If you supply a buffer, it must exist until 
the stream is closed. 


The type must be one of the following: 
Value Meaning 


_IONBF 
No buffer is used. 
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_IOFBF 
Full buffering is used for input and output. Use buf as the buffer and size 
as the size of the buffer. 


_IOLBF 
Line buffering is used. The buffer is deleted when a new-line character is 
written, when the buffer is full, or when input is requested. 


If type is IOFBF or _IOLBF, size is the size of the supplied buffer. If buf is NULL, 
the C library takes size as the suggested size for its own buffer. If type is _IONBF, 
both buf and size are ignored. 


The value for size must be greater than 0. 
Return Value 


The setvbuf() function returns 0 if successful. It returns nonzero if a value that is 
not valid was specified in the parameter list, or if the request cannot be performed. 


The setvbuf() function has no effect on stdout, stdin, or stderr. 


Warning: The array that is used as the buffer must still exist when the specified 
stream is closed. For example, if the buffer is declared within the scope of a 
function block, the stream must be closed before the function is ended and frees the 
storage allocated to the buffer. 


Example that uses setvbuf () 


This example sets up a buffer of buf for stream] and specifies that input to stream2 
is to be unbuffered. 


#include <stdio.h> 
#define BUF_SIZE 1024 


char buf[BUF_SIZE]; 
FILE *streaml, *stream2; 


int main(void) 
{ 
streaml 
stream2 


fopen("myfilel.dat", "r"); 
fopen("myfile2.dat", "r"); 


/* streaml uses a user-assigned buffer of BUF_SIZE bytes */ 
if (setvbuf(streaml, buf, _IOFBF, sizeof(buf)) != 0) 
printf("Incorrect type or size of buffer\n"); 
/* stream2 is unbuffered x/ 
if (setvbuf(stream2, NULL, _IONBF, 0) != 0) 
printf("Incorrect type or size of buffer\n"); 
/* This is a program fragment and not a complete function example */ 


} 


Related Information 
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signal() — Handle Interrupt Signals 


Format 


#include <signal.h> 
void ( *signal (int sig, void(*func)(int)) ) (int); 


Language Level: ANSI 
Description 


The signal () function allows a program to choose one of several ways to handle 
an interrupt signal from the operating system or from the raise() function. If 
compiled with the SYSIFCOPT(*ASYNCSIGNAL) option, this function uses 
asynchronous signals. The asynchronous version of this function behaves like 
sigaction() with SA_NODEFER and SA_RESETHAND options. Asynchronous 
signal handlers may not call abort() or exit(). The remainder of this function 
description will describe synchronous signals. 


The sig argument must be one of the macros SIGABRT, SIGALL, SIGILL, SIGINT, 
SIGFPE, SIGIO, SIGOTHER, SIGSEGV, SIGTERM, SIGUSR1, or SIGUSR2, defined 
in the signal.h include file. SIGALL, SIGIO, and SIGOTHER are only supported by 
the ILE C/C++ Run-time library. The func argument must be one of the macros 
SIG_DFL or SIG_IGN, defined in the <signal.h> include file, or a function address. 


The meaning of the values of sig is as follows: 
Value Meaning 


SIGABRT 
Abnormal termination 


SIGALL 
Catch-all for signals whose current handling action is SIG_DFL. 


When SYSIFCOPT(*ASYNCSIGNAL) is specified, SIGALL is not a catch-all 
signal. A signal handler for SIGALL is only invoked for a user-raised 
SIGALL signal. 


SIGILL 
Detection of a function image that was not valid 


SIGFPE 
Arithmetic exceptions that are not masked, such as overflow, division by 
zero, and operations that are not valid 


SIGINT 
Interactive attention 


SIGIO 
Record file I/O error 


SIGOTHER 
ILE C signal 


SIGSEGV 
Access to memory that was not valid 
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SIGTERM 
End request sent to the program 


SIGUSR1 
Intended for use by user applications. (extension to ANSI) 


SIGUSR2 
Intended for use by user applications. (extension to ANSI) 
The action that is taken when the interrupt signal is received depends on the value 
of func. 
Value Meaning 


SIG_DFL 
Default handling for the signal will occur. 


SIG_IGN 
The signal is to be ignored. 


Return Value 

A return value of SIG_ERR indicates an error in the call to signal (). If successful, 
the call to signal() returns the most recent value of func. The value of errno may 
be set to EINVAL (the signal is not valid). 


Example that uses signal () 


This example shows you how to establish a signal handler. 
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#include <signal.h> 
#include <stdio.h> 

#include <stdlib.h> 
#define ONE_K 1024 


#define OUT_OF_STORAGE (SIGUSR1) 
/* The SIGNAL macro does a signal() checking the return code «/ 
#define SIGNAL(SIG, StrCln) { 


if (signal((SIG), (StrCIn)) == SIG_ERR) { 
perror("Could not signal user signal"); 
abort(); 
} 
} 


void StrCIn(int); 
void DoWork(char **, int); 


a a an a 


int main(int argc, char *argv[]) { 
int size; 
char «buffer; 
SIGNAL(OUT_OF_ STORAGE, StrCln); 
if (argc != 2) { 
printf("Syntax: %s size \n", argv[0]); 
return(-1); 
} 
size = atoi(argv[1]); 
DoWork(&buffer, size); 
return(0); 


} 


void StrCIn(int SIG_TYPE) { 
printf("Failed trying to malloc storage\n"); 
SIGNAL(SIG_TYPE, SIG_DFL); 
exit(0); 

} 


void DoWork(char **buffer, int size) { 
int rc; 
*xbuffer = malloc(size*ONE_K); /* get the size in number of K */ 
if (*buffer == NULL) { 
if (raise(OUT OF _STORAGE)) { 
perror("Could not raise user signal"); 
abort(); 
} 
} 
returns; 


} 


/* This is a program fragment and not a complete function example */ 


Related Information 


sin() — Calculate Sine 


Format 
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#include <math.h> 
double sin(double x); 


Language Level: ANSI 
Description 


The sin() function calculates the sine of x, with x expressed in radians. If x is too 
large, a partial loss of significance in the result may occur. 


Return Value 


The sin() function returns the value of the sine of x. The value of errno may be 
set to either EDOM or ERANGE. 


Example that uses sin() 
This example computes y as the sine of 7/2. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double pi, x, Y3 


pi = 3.1415926535; 
x = pi/2; 
y = sin(x); 


printf("sin( 21f ) = %1f\n", x, y); 
} 


[KEKRKKERKEKEREKERERE RK Output should be similar to: ******keKKKEK 


sin( 1.570796 ) = 1.000000 
*/ 


Related Information 


sinh() — Calculate Hyperbolic Sine 
Format 
#include <math.h> 
double sinh(double x); 
Language Level: ANSI 


Description 
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The sinh() function calculates the hyperbolic sine of x, with x expressed in 
radians. 


Return Value 


The sinh() function returns the value of the hyperbolic sine of x. If the result is 
too large, the sinh() function sets errno to ERANGE and returns the value 
HUGE_VAL (positive or negative, depending on the value of x). 


Example that uses sinh() 
This example computes y as the hyperbolic sine of m/2. 


#include <math.h> 
#include <stdio.h> 


int main(void) 
{ 
double pi, x, Y3 


pi = 3.1415926535; 
x = pi/2; 
y = sinh(x); 


printf("sinh( %1f ) = %1f\n", x, y); 
} 


[ KEKRKEEKRKKERERERERERK Output should be similar to: ****k*k*kkeKEK 


sinh( 1.570796 ) = 2.301299 
*/ 


Related Information 


sprintf() — Print Formatted Data to Buffer 


Format 

#include <stdio.h> 

int sprintf(char «buffer, const char *format-string, argument-list); 

Language Level: ANSI 

Description 

The sprintf() function formats and stores a series of characters and values in the 


array buffer. Any argument-list is converted and put out according to the 
corresponding format specification in the format-string. 
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The format-string consists of ordinary characters and has the same form and 
function as the format-string argument for the printf() function. 


Return Value 


The sprintf() function returns the number of bytes that are written in the array, 
not counting the ending null character. 


Example that uses sprintf () 
This example uses sprintf() to format and print various data. 


#include <stdio.h> 


char buffer[200]; 

int i, j; 

double fp; 

char *s = "baltimore"; 
char c; 


int main(void) 
{ 
Cc eed 
j 353 
fp = 1.7320508; 


/* Format and print various data */ 

j = sprintf(buffer, "%s\n", s); 

j t= sprintf(buffer+j, "%c\n", c); 

j t= sprintf(buffert+j, "%d\n", i); 

j t= sprintf(buffer+j, "%f\n", fp); 
printf("string:\n%s\ncharacter count = %d\n", buffer, j); 


} 


[KEKRKKERKEKERKEKERERE RK Output should be similar to: **x**k*k*kkkKKEK 


string: 
baltimore 
] 

35 
1.732051 


character count = 24 */ 


Related Information 


sqrt() — Calculate Square Root 


Format 
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#include <math.h> 
double sqrt(double x); 


Language Level: ANSI 

Description 

The sqrt() function calculates the nonnegative value of the square root of x. 
Return Value 


The sqrt() function returns the square root result. If x is negative, the function sets 
errno to EDOM, and returns 0. 


Example that uses sqrt () 


This example computes the square root of the quantity that is passed as the first 
argument to main. It prints an error message if you pass a negative value. 


#include <stdio.h> 
#include <stdlib.h> 
#include <math.h> 


int main(int argc, char ** argv) 
{ 

char * rest; 

double value; 


if ( argc != 2) 
printf( "Usage: %s value\n", argv[0] ); 
else 
{ 
value = strtod( argv[1], &rest); 
if ( value < 0.0 ) 
printf( "sqrt of a negative number\n" ); 
else 
printf("sqrt( %1f ) = %1f\n", value, sqrt( value )); 
} 


} 


[KeRKKKKKKKKKKKKKKKKR TF the input TS 45, KRRRKRKKKKRAAKKKEKEE KERR KKKERERE 
KeKKKKKKEKKEKRKE then the output should be similar to: x********x* 


sqrt( 45.000000 ) = 6.708204 
*/ 


Related Information 


srand() — Set Seed for rand() Function 


Format 
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#include <stdlib.h> 
void srand(unsigned int seed); 


Language Level: ANSI 
Thread Safe: NO. 
Description 


The srand() function sets the starting point for producing a series of 
pseudo-random integers. If srand() is not called, the rand() seed is set as if 
srand(1) were called at program start. Any other value for seed sets the generator to 
a different starting point. 


The rand() function generates the pseudo-random numbers. 
Return Value 

There is no return value. 

Example that uses srand() 


This example first calls srand() with a value other than 1 to initiate the random 
value sequence. Then the program computes five random values for the array of 
integers that are called ranvals. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 


int i, ranvals[5]; 


srand(17); 
for (i = 0; i < 5; i++) 
{ 
ranvals[i] = rand(); 
printf("Iteration %d ranvals [%d] = %d\n", i+1, i, ranvals[i]); 
} 
} 


[EK RKERRKEERKREREE Output should be similar to: ***kKKKKEKKKKKKK 


Iteration 1 ranvals [0] = 24107 
Iteration 2 ranvals [1] = 16552 
Iteration 3 ranvals [2] = 12125 
Iteration 4 ranvals [3] = 9427 
Iteration 5 ranvals [4] = 13152 


*/ 


Related Information 


| snprintf() — Print Formatted Data to Buffer 


Format 


| 
| #include <stdio.h> 

| int snprintf(char «buffer, size_t n, const char *format-string, 
| argument-list); 
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Language Level: ANSI 
Description 


The snprintf() function formats and stores a series of characters and values in the 
array buffer. Any argument-list is converted and put out according to the 
corresponding format specification in the format-string. The snprintf() function is 
identical to the sprintf() function with the addition of the n argument, which 
indicates the maximum number of characters (including the ending null character) 
to be written to buffer. 


The format-string consists of ordinary characters and has the same form and 
function as the format string for the printf() function. 


Return Value 


The snprintf() function returns the number of bytes that are written in the array, 
not counting the ending null character. 


Example that uses snprintf() 


This example uses snprintf() to format and print various data. 
#include <stdio.h> 


char buffer[200]; 

int i, 3; 

double fp; 

char *s = "baltimore"; 
char c;3 


int main(void) 


1's 
53 
p = 1.7320508; 

/* Format and print various data */ 

j = sprintf(buffer, 6, "%s\n", s); 

j t= sprintf(buffer+j, 6, "%c\n", c); 

j t= sprintf(buffer+j, 6, "%d\n", i); 

j += sprintf(buffer+j, 6, "%f\n", fp); 
printf("string:\n%s\ncharacter count = %d\n", buffer, j); 


[KEKRKEKRAKKERKERERKERERK Output should be similar to: ******k*kkkKEK 


string: 
baltil 


character count = 15 */ 


Related Information 
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sscanf() — Read Data 


Format 


#include <stdio.h> 
int sscanf(const char «buffer, const char «format, argument-list); 


Language Level: ANSI 
Description 


The sscanf() function reads data from buffer into the locations that are given by 
argument-list. Each argument must be a pointer to a variable with a type that 
corresponds to a type specifier in the format-string. 


Return Value 


The sscanf() function returns the number of fields that were successfully 
converted and assigned. The return value does not include fields that were read 
but not assigned. 


The return value is EOF when the end of the string is encountered before anything 
is converted. 


Example that uses sscanf() 


This example uses sscanf() to read various data from the string tokenstring, and 
then displays that data. 


#include <stdio.h> 
#include <stddef.h> 


int main(void) 


{ 
char *«tokenstring = "15 12 14"; 
wchar_t *«widestring = L"ABC Z"; 
wchar_t ws[81]; 
wchar_t wc; 
int aie 
float fp; 
char s[81]; 
char c; 
/* Input various data x/ 
/* In the first invocation of sscanf, the format string is */ 
/* "%s %c%d%f". If there were no space between %s and %c, */ 
/* sscanf would read the first character following the */ 
/* string, which is a blank space. x/ 
sscanf(tokenstring, "%s %c%d%f", s, &c, &i, &fp); 
sscanf((char *)widestring, "%S %C", ws,&wc); 
/* Display the data */ 
printf("\nstring = %s\n",s); 
printf("character = %c\n",c); 
printf("integer = %d\n",i); 
printf("floating-point number = %f\n", fp); 
printf ("wide-character string = %S\n",ws); 
printf ("wide-character = %C\n",wc); 
} 


[KEKRKKERERERERERK Output should be similar tO: *****KKKKEKKKKKKK 
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string = 15 

character = 1 

integer = 2 
floating-point number 
wide-character string 
wide-character = Z 


14.000000 
ABC 


KKK KKK KK KK RA KKK KKK IKK KKK KKK KKK IK KKK KK AK KK AK KKK KKK AKER AKER KKE | 


Related Information 


strcasecmp() — Compare Strings without Case Sensitivity 


Format 


#include <strings.h> 
int srtcasecmp(const char *stringl, const char *string2); 


Language Level: XPG4 

Description 

The strcasecmp() function compares string] and string2 without sensitivity to case. 
All alphabetic characters in string] and string2 are converted to lowercase before 
comparison. 

The strcasecmp() function operates on null terminated strings. The string 
arguments to the function are expected to contain a null character ('\0') marking 
the end of the string. 


Return Value 


Thestrcasecmp() function returns a value indicating the relationship between the 
two strings, as follows: 


Table 6. Return values of strcasecmp() 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that usesstrcasecmp () 


This example uses strcasecmp() to compare two strings. 
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#include <stdio.h> 
#include <strings.h> 


int main(void) 
char_t *strl 


char_t *str2 
int result; 


"STRING"; 
"string"; 


result = strcasecmp(str1, str2); 
if (result == 0) 
printf("Strings compared equal.\n"); 
else if (result < 0) 
printf("\"%s\" is less than \"%s\".\n", strl, str2); 
else 
printf("\"%s\" is greater than \"%s\".\n", strl, str2); 


return 0; 


} 


/xxxxxxxx The output should be similar to: ****xxxxxxe Kee 
Strings compared equal. 
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Related Information 


strcat() — Concatenate Strings 
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Format 
#include <string.h> 


char *strcat(char *stringl, const char *string2); 
Language Level: ANSI 


Description 


The strcat() function concatenates string2 to string1 and ends the resulting string 
with the null character. 


The strcat() function operates on null-ended strings. The string arguments to the 
function should contain a null character (\0) that marks the end of the string. No 
length checking is performed. You should not use a literal string for a string1 
value, although string2 may be a literal string. 


If the storage of string] overlaps the storage of string2, the behavior is undefined. 
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Return Value 


The strcat() function returns a pointer to the concatenated string (string1). 


Example that uses strcat() 


This example creates the string "computer program" using strcat(). 


#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char bufferl[SIZE] = "computer"; 
char * ptr; 


ptr = strcat( bufferl, " program" ); 
printf( "bufferl = %s\n", bufferl ); 


} 


[xkxxkkexkeexeeee* Output should be similar to: 


bufferl = computer program 


*/ 


Related Information 


KKKKKKKKKKEKEKKEEEE 


strchr() — Search for Character 


Format 
#include <string.h> 
char *strchr(const char «string, int c); 


Language Level: ANSI 


Description 


The strchr() function finds the first occurrence of a character in a string. The 
character c can be the null character (\0); the ending null character of string is 


included in the search. 


The strchr() function operates on null-ended strings. The string arguments to the 


function should contain a null character (\0) that marks the end of the string. 


Return Value 
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The strchr() function returns a pointer to the first occurrence of c that is 
converted to a character in string. The function returns NULL if the specified 
character is not found. 


Example that uses strchr() 


HW 


This example finds the first occurrence of the character "p" in "computer program”. 


#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char buffer1[SIZE] = "computer program"; 
char * ptr; 
int ch = 'p'; 


ptr = strchr( bufferl, ch ); 
printf( "The first occurrence of %c in '%s' is '%s'\n", 
ch, bufferl, ptr ); 
} 


[KEKRKKEREKEREKERE Output should be similar tO: *****KKKKEKKKKKKK 


The first occurrence of p in ‘computer program' is 'puter program' 


*/ 


Related Information 


strcmp() — Compare Strings 
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Format 
#include <string.h> 


int strcmp(const char *stringl, const char *string2); 

Language Level: ANSI 

Description 

The strcmp() function compares string] and string2. The function operates on 


null-ended strings. The string arguments to the function should contain a null 
character (\0) that marks the end of the string. 
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Return Value 


The strcmp() function returns a value indicating the relationship between the two 
strings, as follows: 


Value Meaning 

Less than 0 string] less than string2 

0 string] identical to string2 
Greater than 0 string] greater than string2 


Example that uses strcmp () 
This example compares the two strings that are passed to main() using strcmp(). 


#include <stdio.h> 
#include <string.h> 


int main(int argc, char ** argv) 
{ 
int result; 


if ( argc != 3 ) 
{ 


printf( "Usage: %s stringl string2\n", argv[0] ); 


} 
else 
{ 
result = strcmp( argv[1], argv[2] ); 
if ( result == 0 ) 
printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] ); 
else if ( result < 0 ) 
printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] ); 
else 
printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] ); 
} 
} 


[KekKKKKKKKKKKKKKKK TF the input is the strings KKKKKKKKKKK KERR KKKKEKEKKK 


xekxexeeee "is this first?" and "is this before that one?", ****x*xxxxx* 
KKKKEKKKKKEKEKKKERK then the expected output TSf RR KKKKKKKKEKKKKEKEKER 


"is this first?" is greater than "is this before that one?" 
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Related Information 
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strcmpi - Compare Strings Without Case Sensitivity 
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Format 

#include <string.h> 

int strcmpi(const char *stringl, const char *string2); 

Note: The strcmpi function is supported only for C++, not for C. 

Language Level: Extension 

Description 

strcmpi compares string] and string2 without sensitivity to case. All alphabetic 
characters in the two arguments string] and string2 are converted to lowercase 


before the comparison. 


The function operates on null-ended strings. The string arguments to the function 
are expected to contain a null character (\0) marking the end of the string. 


Return Value 


strcmpi returns a value indicating the relationship between the two strings, as 
follows: 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that uses strcmpi () 


This example uses strcmpi to compare two strings. 
#include <stdio.h> 
#include <string.h> 
int main(void) 
{ 
/* Compare two strings without regard to case */ 
if (Q == strcempi("hello", "HELLO")) 
printf("The strings are equivalent.\n"); 
else 
printf("The strings are not equivalent.\n"); 
return 0; 


} 


The output should be: 
The strings are equivalent. 


Related Information: 
* strcoll 
° strespn 
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° strcmp 


* wcscmp 
* wcsncmp 

° <string.h> 
* strcasecmp 
° strncasecmp 


strcoll() — Compare Strings 
Format 
#include <string.h> 
int strcoll(const char *stringl, const char *string2); 
Language Level: ANSI 


Description 


The strcol1() function compares two strings using the collating sequence that is 
specified by the program’s locale. 


The behavior of this function is affected by the LC_COLLATE category of the 
current locale. 


Return Value 


The strcol1() function returns a value indicating the relationship between the 
strings, as listed below: 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


If strcol1() is unsuccessful, errno is changed. The value of errno may be set to 
EINVAL (the string] or string2 arguments contain characters that are not available 
in the current locale). 


Example that uses strcol] () 


This example compares the two strings that are passed to main() using strcol1(): 
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#include <stdio.h> 
#include <string.h> 


int main(int argc, char ** argv) 
{ 


int result; 
if ( argc != 3 ) 
{ 


printf( "Usage: %s stringl string2\n", argv[0] ); 
} 
else 


{ 
result = strcoll( argv[1], argv[2] ); 


if ( result == 0 ) 
printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] ); 
else if ( result < 0 ) 
printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] ); 
else 
printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] ); 
} 


[KeKKKKKKKKKKKKKKKK TF the input is the strings KKK KKK KK KKK KEKE RK ERERRER 
KRKKEKKEKKEEKREKRKRKK FT rststring" and "secondstring", KKK KKKEK KKK ERERERKEER 
KRKKKKKKEKKKKEKKKER then the expected OUtPUt 1S: KxRKKKKKKKKKKKKEK 


"firststring" is less than "secondstring" 
*/ 


Related Information 


strcpy() — Copy Strings 
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Format 

#include <string.h> 

char *strcpy(char *stringl, const char *string2); 
Language Level: ANSI 


Description 


The strcpy() function copies string2, including the ending null character, to the 
location that is specified by string1. 


The strcpy() function operates on null-ended strings. The string arguments to the 
function should contain a null character (\0) that marks the end of the string. No 
length checking is performed. You should not use a literal string for a string1 
value, although string2 may be a literal string. 


Return Value 


The strcpy() function returns a pointer to the copied string (string). 
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Example that uses strcpy() 
This example copies the contents of source to destination. 


#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char source[SIZE] = "This is the source string"; 
char destination[SIZE] = "And this is the destination string"; 
char * return_string; 


printf( "destination is originally = \"%s\"\n", destination ); 
return_string = strcpy( destination, source ); 
printf( "After strcpy, destination becomes \"%s\"\n", destination ); 


} 

[KEKKRKRRKRKEKERERERK Output Should be similar tO: ***kKKKKKKKKKEKKK 
destination is originally = "And this is the destination string" 
After strcpy, destination becomes "This is the source string" 


*/ 


Related Information 


strcspn() — Find Offset of First Character Match 


Format 

#include <string.h> 

size_t strcspn(const char *stringl, const char *string2); 

Language Level: ANSI 

Description 

The strcspn() function finds the first occurrence of a character in string1 that 
belongs to the set of characters that is specified by string2. Null characters are not 


considered in the search. 


The strcspn() function operates on null-ended strings. The string arguments to the 
function should contain a null character (\0) marking the end of the string. 


Return Value 
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The strcspn() function returns the index of the first character found. This value is 
equivalent to the length of the initial substring of string1 that consists entirely of 
characters not in string2. 


Example that uses strcspn() 


This example uses strcspn() to find the first occurrence of any of the characters 


non one aye no 
y y 


ay Xx or "e” in string. 


#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char string[SIZE] = "This is the source string"; 
char * substring = "axle"; 


printf( "The first %i characters in the string \"%s\" " 


"are not in the string \"%s\" \n", 
strcspn(string, substring), string, substring); 


} 

/xxxxxxeeee Output should be similar to: *****xexxee Ke 

The first 10 characters in the string "This is the source string" 
are not in the string "axle" 


*/ 


Related Information 


strdup - Duplicate String 


332 


Format 

#include <string.h> 

char *strdup(const char *string); 

Note: The strdup function is supported only for C++, not for C. 

Language Level: XPG4, Extension 

Description 

strdup reserves storage space for a copy of string by calling malloc. The string 


argument to this function is expected to contain a null character (\0) marking the 
end of the string. Remember to free the storage reserved with the call to strdup. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Return Value 


strdup returns a pointer to the storage space containing the copied string. If it 
cannot reserve storage strdup returns NULL. 


Example that uses strdup() 


This example uses strdup to duplicate a string and print the copy. 


#include <stdio.h> 
#include <string.h> 
int main(void) 
{ 
char «string = "this is a copy"; 
char *newstr; 
/* Make newstr point to a duplicate of string */ 
if ((newstr = strdup(string)) != NULL) 
printf("The new string is: %s\n", newstr); 
return 0; 


} 


The output should be: 
The new string is: this is a copy 


Related Information: 
° strcepy 

° strncpy 

* wescpy 

* wesncpy 

° Strings 

° <string.h> 


strerror() — Set Pointer to Run-Time Error Message 


Format 

#include <string.h> 

char *strerror(int errnum) ; 
Language Level: ANSI 


Description 


The strerror() function maps the error number in errnum to an error message 
string. 


Return Value 

The strerror() function returns a pointer to the string. The function returns the 
string in the CCSID of the job. The function does not use the program locale in any 
way. It does not return a NULL value. 


Example that uses strerror() 


This example opens a file and prints a run-time error message if an error occurs. 
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#include <stdlib.h> 
#include <string.h> 
#include <errno.h> 
int main(void) 


FILE «stream; 


if ((stream = fopen("mylib/myfile", "r")) == NULL) 
printf(" %s \n", strerror(errno)); 


} 


/* This is a program fragment and not a complete function example */ 


Related Information 


| strfmon() — Convert Monetary Value to String 
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Format 


#include <monetary.h> 
int strfmon(char *s, size_t maxsize, const char *format, argument_list); 


Language Level: XPG4 
Thread Safe: YES. 
Description 


The strfmon() function places characters into the array pointed to by s as 
controlled by the string pointed to by format. No more than maxsize characters are 
placed into the array. 


The character string format contains two types of objects: plain characters, which 
are copied to the output stream, and directives, each of which results in the 
fetching of zero or more arguments, which are converted and formatted. The 
results are undefined if there are insufficient arguments for the format. If the 
format is exhausted while arguments remain, the excess arguments are simply 
ignored. Only 15 significant digits are guaranteed on conversions involving double 
values. 


A directive consists of a % character, optional conversion specifications, and a 
ending character that determines the directive’s behavior. 


A directive consists of the following sequence: 

¢ A % character. 

* Optional flags. 

* Optional field width. 

* Optional left precision. 

* Optional right precision. 

* A required conversion character indicating the type of conversion to be 
performed. 
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Table 7. Flags 


Flag 


Meaning 


=f 


An = followed by a single character f which is used 
as the numeric fill character. By default the numeric 
fill character is a space character. This flag does not 
affect field width filling, which always uses a space 
character. This flag is ignored unless left precision is 
specified. 


Do not use grouping characters when formatting 
the currency value. Default is to insert grouping 
characters as defined in the current locale. 


+ or ( 


Specify the style representing positive and negative 
currency amounts. If + is specified, the locale’s 
equivalent of + and — for monetary quantities will 
be used. If (is specified, negative amounts are 
enclosed within parenthesis. Default is +. 


Do not output the currency symbol. Default is to 
output the currency symbol. 


Use left justification for double arguments. Default 
is right justification. 


Field Width 


w 


A decimal digit string w specifying a minimum field width in bytes in 
which the result of the conversion is right-justified (or left-justified if the 
flag - is specified). The default is 0. 


Left Precision 


#n 


A # followed by a decimal digit string n specifying a maximum number of 
digits expected to be formatted to the left of the radix character. This 
option can be used to keep the formatted output from multiple calls to 
strfmon() aligned in the same columns. It can also be used to fill unused 
positions with a special character as in $***123.45. This option causes an 
amount to be formatted as if it has the number of digits specified by n. If 
more than n digit positions are required, this conversion specification is 
ignored. Digit positions in excess of those actually required are filled with 
the numeric fill character (see the =f flag above). 


If grouping has not been suppressed withe the © flag, and it is defined for 
the current locale, grouping separators are inserted before the fill charcters 
(if any) are added. Grouping separators are not applied to fill characters 
even if the fill character is a digit. To ensure alignment, any characters 
appearing before or after the number in the formatted output, such as 
currency or sign symbols, are padded as necessary with space characters to 
make their positive and negative formats an equal length. 


Right Precision 


-P 


A period followed by a decimal digit string p specifies the number of digits 
after the radix character. If the value of the right precision p is 0, no radix 
character appears. If a right precision is not specified, a default specified 
by the current locale is used. The amount being formatted is rounded to 
the specified number of digits prior to formatting. 
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Table 8. Conversion Characters 


Specifier Meaning 


%i The double argument is formatted according to 
the locale’s international currency format. 


%N The double argument is formatted according to 
the locale’s national currency format. 


%%o Is replaced by %. No argument is converted. 


Note: This function is only accessible if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


If the total number of resulting bytes including the ending null character is not 
more than maxsize, the strfmon() function returns the number of bytes placed into 
the array pointed to by s, but excludes the ending null character. Otherwise, zero is 
returned, and the contents of the array are undefined. 


The value of errno may be set to: 


E2BIG Conversion stopped due to lack of space in the buffer. 


Example that uses strfmon() 


#include <stdio.h> 
#include <monetary.h> 
#include <locale.h> 


int main(void) 
{ 
char string[100]; 
double money = 1234.56; 
if (setlocale(LC_ALL, "/qsys.lib/en_us.locale") == NULL) { 
printf("Unable to setlocale().\n"); 
exit(1); 
} 


strfmon(string, 100, "%i", money); /* USD 1,234.56 */ 
printf("%s\n", string); 

strfmon(string, 100, "%n", money); /* $1,234.56 */ 
printf("%s\n", string); 


+ 


} 


[BERR KKK KEKE AK KER KKK K KEKE KEI KERIKERI KKK EK AKI KEI KEE AEE 


The output should be similar to: 
USD 1,234.56 
$1,234.56 


KKK KKK KKK KK EAR KEK KKK KKK KKK AKER AK KEI KK AKKEA AKER AKER EKER | 


Related Information 


| strftime() — Convert Date/Time to String 


Format 


size_t strftime(char *s, size_t maxsize, const char *format, 


| 
| #include <time.h> 
| 
| const struct tm *timeptr); 


336 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Language Level: ANSI 
Thread Safe: YES. 
Description 


The strfttime() function places bytes into the array pointed to by s as controlled 
by the string pointed to by format. The format string consists of zero or more 
conversion specifications and ordinary characters. A conversion specification 
consists of a % character and a terminating conversion character that determines 
the behavior of the conversion.All ordinary characters (including the terminating 
null byte, and multi-byte chars) are copied unchanged into the array. If copying 
takes place between objects that overlap, then the behavior is undefined. No more 
than maxsize bytes are placed in the array. The appropriate characters are 
determined by the values contained in the structure pointed to by timeptr, and by 
the values stored in the current locale. 


Each standard conversion specification is replaced by appropriate characters as 
described in the following table: 


Specifier Meaning 

%oa Abbreviated weekday name. 

SA Full weekday name. 

%ob Abbreviated month name. 

%B Full month name. 

%oc Date/Time in the format of the locale. 

%C Century number [00-99], the year divided by 100 and truncated to an 
integer. 

%od Day of the month [01-31]. 

%D Date Format, same as %m/%d/“%y. 

%e Same as %d, except single digit is preceded by a space [1-31]. 

%h Same as %b. 

%H Hour in 24-hour format [00-23]. 

%l Hour in 12-hour format [01-12]. 

%oj Day of the year [001-366]. 

%om Month [01-12]. 

%M Minute [00-59]. 

%on Newline character. 

Yop AM or PM string. 

Yor Time in AM/PM format of the locale. If not available in the locale time 
format, defaults to the POSIX time AM/PM format: %I:%M:%S %p. 

%R 24-hour time format without seconds, same as %H:%M. 

%S Second [00-61]. The range for seconds allows for a leap second and a 
double leap second. 

ot Tab character. 

%T 24-hour time format with seconds, same as %H:%M:%S. 

%ou Weekday [1,7]. Monday is 1 and Sunday is 7. 

%U Week number of the year [00-53]. Sunday is the first day of the week. 
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Specifier 


Meaning 


%oV 


ISO week number of the year[01-53]. Monday is the first day of the 
week. If the week containing January 1st has four or more days in the 
new year then it is considered week 1. Otherwise, it is the last week of 
the previous year, and the next year is week 1 of the new year. 


YW 


Weekday [0,6], Sunday is 0. 


%oW 


Week number of the year [00-53]. Monday is the first day of the week. 


%X 


Date in the format of the locale. 


%oX 


Time in the format of the locale. 


oy 


2 digit year [00,99]. 


YoY 
%L, 


4-digit year. Can be negative. 


Time zone name. Available only from the locale. 


%o%o 


% character. 


Modified Conversion Specifiers 


Some conversion specifiers can be modified by the E or O modifier characters to 
indicate that an alternate format or specification should be used rather than the 
one normally used by the unmodified conversion specifier. If a modified 
conversion specifier uses a field in the current locale that is unavailable, then the 
behavior will be as if the unmodified conversion specification were used. For 


example, if the era string is the empty string 


mn 


, Which means that the string is 


unavailable, then %EY would act like %Y. 


Specifier 


Meaning 


%EC 


Date/time for current era. 


EC 
%EX 


Era name. 


Date for current era. 


%EX 
% oEy 


Time for current era. 


Era year. This is the offset from the base year. 


EY 


Year for current era. 


%Od 


Day of the month using alternate digits. 


%OeWe 


Same as %Od. 


%OH 


Hour in 24 hour format using alternate digits. 


%OI 


Hour in 12 hour format using alternate digits. 


%Om 


Month using alternate digits. 


%OM 


Minutes using alternate digits. 


%OS 


Seconds using alternate digits. 


%Ou 


Weekday using alternate digits. Monday is 1 and Sunday is 7. 


%OU 


Week number of the year using alternate digits. Sunday is the first day 
of the week. 


%OV 


ISO week number of the year using alternate digits. See %V for 
explanation on ISO week number. 


VOW 


Weekday using alternate digits. Sunday is 0. 


SOW 


Week number of the year using alternate digits. Monday is the first day 
of the week. 
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Specifier Meaning 


YOY 


2-digit year using alternate digits. 


Note: %C, %D, %e, %h, Yon, Yr, %R, Yt, %T, Yu, %V and the modified conversion 
specifiers are not available unless LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


If the total number of resulting bytes including the terminating null byte is not 


more than maxsize, strftime() returns the number of bytes placed into the array 
pointed to by s, not including the terminating null byte. Otherwise, 0 is returned 
and the contents of the array are indeterminate. 


Example that uses strftime() 


#include <stdio.h> 
#include <time.h> 


int main(void) 


{ 


} 


char s[100]; 

int rc; 

time_t temp; 
struct tm *timeptr; 


temp = time(NULL) ; 
timeptr = localtime(&temp) ; 


rc = strftime(s,sizeof(s),"Today is %A, %b %d.\nTime: 


printf("%d characters written.\n%s\n",rc,s); 


return 0; 


[KEK KERR KK EAR KAR KEK K KKK KKK KKK KEE AK KEIR KEKE KEK 


The output should be similar to: 
46 characters written 

Today is Wednesday, Oct 24. 
Time: 01:01:15 PM 


sr", timeptr); 


KKK KKK KKK KKK AK KK AK KKK KKK KK KEK KKK IKKE KKK A KKK IKKE KAKA K ERK | 


Related Information 
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stricmp - Compare Strings without Case Sensitivity 


340 


Format 

#include <string.h> 

int stricmp(const char *stringl, const char *string2); 

Note: The stricmp function is supported only for C++, not for C. 

Language Level: Extension 

Description 

stricmp compares string] and string2 without sensitivity to case. All alphabetic 
characters in the two arguments string] and string2 are converted to lowercase 


before the comparison. 


The function operates on null-ended strings. The string arguments to the function 
are expected to contain a null character (\0) marking the end of the string. 


Return Value 


stricmp returns a value indicating the relationship between the two strings, as 
follows: 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that uses stricmp() 


This example uses stricmp to compare two strings. 


#include <stdio.h> 
#include <string.h> 
int main(void) 
{ 
/* Compare two strings as lowercase */ 
if (0 == stricmp("hello", "HELLO")) 
printf("The strings are equivalent.\n"); 
else 
printf("The strings are not equivalent.\n"); 
return 0; 


} 


The output should be: 


The strings are equivalent. 


Related Information: 


° strcoll 
° strespn 
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* wescmp 
* wesnemp 
° <string.h> 


strien() — Determine String Length 


Format 


#include <string.h> 
size_t strlen(const char *string); 


Language Level: ANSI 
Description 


The strlen() function determines the length of string excluding the ending null 
character. 


Return Value 

The strlen() function returns the length of string. 

Example that uses strlen() 

This example determines the length of the string that is passed to main(). 


#include <stdio.h> 
#include <string.h> 


int main(int argc, char ** argv) 


{ 


if ( argc != 2 ) 
printf( "Usage: %s string\n", argv[0] ); 
else 
printf( "Input string has a length of %i\n", strlen( argv[1] )); 


[KekKKKKKKKKKKKKKKEK TF the input is the string KKKKKK EKER ERE RRERKERER 


KRKEKEKKKKERKKKKEEKE "HOW long is this string?", KRKEKKEKKEKEKKEKKERE 
KKKKKKKKKKKKKKKKER then the expected OUtPUt 1S: KxKKKKRKKKKKKKKEK 


Input string has a length of 24 
x/ 


Related Information 


strncasecmp() — Compare Strings without Case Sensitivity 


Format 
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#include <strings.h> 
int srtncasecmp(const char *stringl, const char *string2, size_t count); 


Language Level: XPG4 

Description 

The strncasecmp() function compares up to count characters of string1 and string2 
without sensitivity to case. All alphabetic characters in string1 and string2 are 
converted to lowercase before comparison. 

The strncasecmp() function operates on null terminated strings. The string 
arguments to the function are expected to contain a null character ('\0') marking 
the end of the string. 


Return Value 


Thestrncasecmp() function returns a value indicating the relationship between the 
two strings, as follows: 


Table 9. Return values of strncasecmp () 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that usesstrncasecmp () 


This example uses strncasecmp() to compare two strings. 


#include <stdio.h> 
#include <strings.h> 


int main(void) 


"STRING ONE"; 
"string TWO"; 


char_t *strl 
char_t *str2 
int result; 


result = strncasecmp(strl, str2, 6); 
if (result == 0) 
printf("Strings compared equal.\n"); 
else if (result < 0) 
printf("\"%s\" is less than \"%s\".\n", strl, str2); 
else 
printf("\"%s\" is greater than \"%s\".\n", strl, str2); 


return 0; 


} 


/xxxxxxxe The output should be similar to: ****xxxxxee kee 
Strings compared equal. 


KKK KKK KKK KK EA KK EAR KKK AKER KEKE RAKE | 


Related Information 
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strncat() — Concatenate Strings 


Format 

#include <string.h> 

char *strncat(char *stringl, const char *string2, size_t count); 

Language Level: ANSI 

Description 

The strncat() function appends the first count characters of string2 to string1 and 
ends the resulting string with a null character (\0). If count is greater than the 


length of string2, the length of string2 is used in place of count. 


The strncat() function operates on null-ended strings. The string argument to the 
function should contain a null character (\0) marking the end of the string. 


Return Value 

The strncat() function returns a pointer to the joined string (string1). 

Example that uses strncat() 

This example demonstrates the difference between strcat() and strncat(). The 


strcat() function appends the entire second string to the first, whereas strncat() 
appends only the specified number of characters in the second string to the first. 
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#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char bufferl[SIZE] = "computer"; 
char * ptr; 


/* Call strcat with bufferl and " program" */ 


ptr = strcat( bufferl, " program" ); 
printf( "strcat : bufferl = \"%s\"\n", bufferl ); 


/* Reset bufferl to contain just the string "computer" again */ 


memset( bufferl, '\0', sizeof( bufferl )); 
ptr = strcpy( bufferl, "computer" ); 


/* Call strncat with bufferl and " program" */ 

ptr = strncat( bufferl, " program", 3 ); 

printf( "strncat: bufferl = \"%s\"\n", bufferl ); 
} 


[KEKRKREREKERERERK Output should be similar tO: *****KKKKEKKKKKKK 
strcat : bufferl = "computer program" 

strncat: bufferl = "computer pr" 

*/ 


Related Information 


strncmp() — Compare Strings 
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Format 

#include <string.h> 

int strncmp(const char *stringl, const char *string2, size_t count); 

Language Level: ANSI 

Description 

The strncmp() function compares string] and string2 to the maximum of count. 


Return Value 


The strncmp() function returns a value indicating the relationship between the 
strings, as follows: 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that uses strncmp() 


This example demonstrates the difference between the strcmp() function and the 


strncmp() function. 


#include <stdio.h> 
#include <string.h> 


#define SIZE 10 


int main(void) 
{ 
int result; 
int index = 3; 
char buffer1[SIZE] "abcdefg"s 
char buffer2[SIZE] = "abcfg"; 
void print_result( int, char *, char * ); 


result = strcemp( bufferl, buffer2 ); 
printf( "Comparison of each character\n" ); 
printf( "strcmp: " ); 

print_result( result, bufferl, buffer2 ); 


result = strncmp( bufferl, buffer2, index); 
printf( "\nComparison of only the first %i characters\n", index ); 
printf( "  strncmp: " ); 
print_result( result, bufferl, buffer2 ); 
} 


void print_result( int res, char * p_bufferl, char * p_buffer2 ) 


{ 


if ( res == 

printf( "\"%s\" is identical to \"%s\"\n", p_bufferl, p_buffer2); 
else if ( res < 0 ) 

printf( "\"%s\" is less than \"%s\"\n", p_bufferl, p_buffer2 ); 
else 

printf( "\"%s\" is greater than \"%s\"\n", p_bufferl, p_buffer2 ); 


[KEKRKERKRKEKRERERERE Output Should be similar tO: *****KKKKKKKKEKKK 


Comparison of each character 
strcmp: "“abcdefg" is less than "abcfg" 


Comparison of only the first 3 characters 
strncmp: "abcdefg" is identical to "abcfg" 
*/ 


Related Information 
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strncpy() — Copy Strings 
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Format 

#include <string.h> 

char *strncpy(char *stringl, const char *string2, size_t count); 

Language Level: ANSI 

Description 

The strncpy() function copies count characters of string2 to string1. If count is less 
than or equal to the length of string2, a null character (\0) is not appended to the 
copied string. If count is greater than the length of string2, the string1 result is 
padded with null characters (\0) up to length count. 

Return Value 

The strncpy() function returns a pointer to string1. 


Example that uses strncpy() 


This example demonstrates the difference between strcpy() and strncpy(). 
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#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char source[ SIZE ] = "123456789"; 
char sourcel[ SIZE ] = "123456789"; 
char destination[ SIZE ] = "abcdefg"; 
char destinationl[ SIZE ] = "abcdefg"; 
char * return_string; 
int index = 5; 


/* This is how strcpy works */ 

printf( "destination is originally = '%s'\n", destination ); 
return_string = strcpy( destination, source ); 

printf( "After strcpy, destination becomes '%s'\n\n", destination ); 


/* This is how strncpy works */ 

printf( "destinationl is originally = '%s'\n", destinationl ); 
return_string = strncpy( destinationl, sourcel, index ); 

printf( "After strncpy, destinationl becomes '%s'\n", destinationl ); 


} 


[KEKRKEEREKERERERK Output Should be similar tO: *****KKKKKKKKKKKK 


destination is originally = 'abcdefg' 
After strcpy, destination becomes '123456789' 


destinationl is originally = 'abcdefg' 
After strncpy, destinationl becomes '12345fg' 
*/ 


Related Information 


<string.h>” on page 1 


strnicmp - Compare Substrings Without Case Sensitivity 
Format 
#include <string.h> 
int strnicmp(const char *stringl, const char *string2, int n); 
Note: The strnicmp function is supported only for C++, not for C. 
Language Level: Extension 


Description 


strnicmp compares, at most, the first 1 characters of string1 and string2 without 
sensitivity to case. 
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The function operates on null terminated strings. The string arguments to the 
function are expected to contain a null character (\0) marking the end of the 
string. 


Return Value 


strnicmp returns a value indicating the relationship between the substrings, as 
follows: 


Value Meaning 

Less than 0 substring1 less than substring2 

0 substring] equivalent to substring2 
Greater than 0 substring1 greater than substring2 


Example that uses strnicmp() 


This example uses strnicmp to compare two strings. 


#include <stdio.h> 
#include <string.h> 
int main(void) 
{ 
char *strl "THIS IS THE FIRST STRING"; 
char *str2 "This is the second string"; 
int numresult; 
/* Compare the first 11 characters of strl1 and str2 
without regard to case x/ 
numresult = strnicmp(str1, str2, 11); 
if (numresult < 0) 
printf("String 1 is less than string2.\n"); 
else 
if (numresult > 0) 
printf("String 1 is greater than string2.\n"); 
else 
printf("The two strings are equivalent.\n"); 
return 0; 


} 


The output should be: 


The two strings are equivalent. 


Related Information: 


° strncmp 
* wcescmp 
* wcesncmp 
* <string.h> 


strpbrk() — Find Characters in String 
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Format 


#include <string.h> 
char *strpbrk(const char *stringl, const char *string2); 


Language Level: ANSI 
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Description 


The strpbrk() function locates the first occurrence in the string pointed to by 
string] of any character from the string pointed to by string2. 


Return Value 


The strpbrk() function returns a pointer to the character. If string1 and string2 
have no characters in common, a NULL pointer is returned. 


Example that uses strpbrk() 


This example returns a pointer to the first occurrence in the array string of either a 
or b. 


#include <stdio.h> 
#include <string.h> 


int main(void) 

{ 
char *result, *string = "A Blue Danube"; 
char *chars = "ab"; 


result = strpbrk(string, chars); 
printf("The first occurrence of any of the characters \"%s\" in " 
"\"%s\" is \"%s\"\n", chars, string, result); 
} 
[KEKKRKKKKRKEKERKERER Output Should be similar tO: **XkKKKKKKKKKEKKK 
The first occurrence of any of the characters "ab" in "The Blue Danube" 
is "anube" 


/ 


Related Information 


strnset - strset 


- Set Characters in String 


Format 


#include <string.h> 
char *strnset(char *string, int c, size_t n); 
char *strset(char «string, int c); 


Note: The strnset and strset functions are supported only for C++, not for C. 
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Language Level: Extension 
Description 


strnset sets, at most, the first n characters of string to c (converted to a char). If n 
is greater than the length of string, the length of string is used in place of n. strset 
sets all characters of string, except the ending null character (\0), to c (converted to 
a char). For both functions, the string is a null-terminated string. 


Return Value 


Both strset and strnset return a pointer to the altered string. There is no error 
return value. 


Example that uses strnset() and strset() 


In this example, strnset sets not more than four characters of a string to the 
character ’x’. Then the strset function changes any non-null characters of the 
string to the character ’k’. 
#include <stdio.h> 
#include <string.h> 
int main(void) 
{ 
char str[] = "abcdefghi"; 
printf("This is the string: %s\n", str); 
printf("This is the string after strnset: %s\n", strnset((char*)str, 'x', 4)); 
printf("This is the string after strset: %s\n", strset((char*)str, 'k')); 
return 0; 


} 


The output should be: 


This is the string: abcdefghi 
This is the string after strnset: xxxxefghi 
This is the string after strset: kkkkkkkkk 


Related Information: 
¢ strchr 

* strpbrk 

* weschr 

* wespbrk 

° <string.h> 


strptime()— Convert String to Date/Time 
Format 
#include <time.h> 
char *strptime(const char *buf, const char «format, struct tm «tm); 
Language Level: XPG4 
Thread Safe: YES. 


Description 
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The strptime() function converts the character string pointed to by buf to values 
that are stored in the fm structure pointed to by tm, using the format specified by 
format. 


The format contains zero or more directives. A directive contains either an ordinary 
character (not % or a white space), or a conversion specification. Each conversion 
specification is composed of a % character followed by one or more conversion 
characters, which specify the replacement required. There must be a white space or 
other delimiter in both buf and format to be guaranteed that the function will 
behave as expected. There must be a delimiter between two string-to-number 
conversions, or the first number conversion may convert characters that belong to 
the second conversion specifier. 


Any whitespace (as specified by isspace()) encountered before a directive is 
scanned in either the format string or the input string will be ignored. A directive 
that is an ordinary character must exactly match the next scanned character in the 
input string. Case is relevant when matching ordinary character directives. If the 
ordinary character directive in the format string does not match the character in 
the input string, strptime is not successful. No more characters will be scanned. 


Any other conversion specification is matched by scanning characters in the input 
string until a character that is not a possible character for that specification is 
found or until no more characters can be scanned. If the specification was 
string-to-number, the possible character range is +,- or a character specified by 
isdigit(). Number specifiers do not require leading zeros. If the specification 
needs to match a field in the current locale, scanning is repeated until a match is 
found. Case is ignored when matching fields in the locale. If a match is found, the 
structure pointed to by tm will be updated with the corresponding locale 
information. If no match is found, strptime is not successful. No more characters 
will be scanned. 


Missing fields in the tm structure may be filled in by strftime if given enough 
information. For example, if a date is given, tm_yday can be calculated. 


Each standard conversion specification is replaced by appropriate characters as 
described in the following table: 


Specifier Meaning 

%a Name of day of the week, can be either the full name or an 
abbreviation. 

YA Same as %a. 

%b Month name, can be either the full name or an abbreviation. 

%B Same as %b. 

%c Date/time, in the format of the locale. 

%C Century number [00-99]. Calculates the year if a two-digit year is used. 

%od Day of the month [1-31]. 

%D Date format, same as Y%m/%d/“%y. 

%oe Same as %d. 

%h Same as %b. 

%H Hour in 24-hour format [0-23]. 

%l Hour in 12-hour format [1-12]. 

%oj Day of the year [1-366]. 
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Specifier 


Meaning 


%m. 


Month [1-12]. 


%M 


Minute [0-59]. 


%N. 


Skip all whitespaces until a newline character is found. 


%op 


or 


AM or PM string, used for calculating the hour if 12-hour format is 
used. 


Time in AM/PM format of the locale. If not available in the locale time 
format, defaults to the POSIX time AM/PM format: %I:%M:%S %p. 


%R 


24-hour time format without seconds, same as %H:%M. 


%S 


Yot 


Second [00-61]. The range for seconds allows for a leap second and a 
double leap second. 


Skip all whitespaces until a tab character is found. 


%T 


%ou. 


24 hour time format with seconds, same as %H:%M:%8S . 


Weekday [1-7]. Monday is 1 and Sunday is 7. 


%U 


Week number of the year [1-53], Sunday is the first day of the week. 
Used in calculating the day of the year. 


%oV 


ISO week number of the year [1-53]. Monday is the first day of the 
week. If the week containing January 1st has four or more days in the 
new year, it is considered week 1. Otherwise, it is the last week of the 
previous year, and the next week is week 1 of the new year. Used in 
calculating the day of the year. 


YW 


Weekday [0 -6]. Sunday is 0. 


%oW 


Week number of the year [0-53]. Monday is the first day of the week. 
Used in calculating the day of the year. 


%X 


Date in the format of the locale. 


%oX 
% oy 


Time in the format of the locale. 


2-digit year [0-99]. 


YY 
%L, 


4-digit year. Can be negative. 


Time zone name. Available only from the locale. Used to determine if 
the locale is in daylight savings time. 


%o%o 


% character. 


Modified Conversion Specifiers 


Some conversion specifiers can be modified by the E or O modifier characters to 
indicate that an alternate format or specification should be used. If a modified 
conversion specifier uses a field in the current locale that is unavailable, then the 
behavior will be as if the unmodified conversion specification were used. For 


example, if the era string is the empty string 


mn 


, Which means that era is 


unavailable, then %EY would act like %Y. 


Specifier 


Meaning 


%EC 


Date/time for current era. 


%EC 


Era name. 


%EX 


Date for current era. 


%EX 


Time for current era. 


Ey 


Era year. This is the offset from the base year. 
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Specifier Meaning 

YEY Year for the current era. 

%Od Day of the month using alternate digits. 

%O4e Same as %Od. 

%OH Hour in 24-hour format using alternate digits. 

%OI Hour in 12-hour format using alternate digits. 

%Om Month using alternate digits. 

%OM Minutes using alternate digits. 

%OS Seconds using alternate digits. 

%Ou Day of the week using alternate digits. Monday is 1 and Sunday is 7. 

%OU Week number of the year using alternate digits. Sunday is the first day 
of the week. 

SOW Weekday using alternate digit. Sunday is 0 and Saturday is 6. 

SOW Week number of the year using alternate digits. Monday is the first day 
of the week. 

%Oy 2-digit year using alternate digits. 


Note: This function is only accessible if LOCALETYPE(*LOCALE) or 


LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


On successful completion, the strptime() function returns a pointer to the 
character following the last character parsed. Otherwise, a null pointer is returned. 


Example that uses strptime() 


#include <stdio.h> 
#include <locale.h> 
#include <time.h> 


int main(void) 


{ 


char buf[100]; 
time_t t; 
struct tm *timeptr,result; 


setlocale(LC_ALL,"/QSYS.LIB/EN_US.LOCALE") ; 

t = time(NULL); 

timeptr = localtime(&t) ; 

strftime(buf,sizeof (buf), "%a %m/%d/%Y %r", timeptr) ; 


if(strptime(buf, "%a %m/%d/%Y %r",&result) == NULL) 
printf("\nstrptime failed\n"); 


else 

{ 
printf("tm_hour: %d\n",result.tm_hour) ; 
printf("tmmin: %d\n",result.tm_min); 
printf("tm_sec: %d\n",result.tm_sec); 
printf("tm_mon: %d\n",result.tm_mon) ; 
printf("tm_mday: %d\n",result.tm_mday) ; 
printf("tm_year: %d\n",result.tm_year) ; 
printf("tm_yday: %d\n",result.tm_yday) ; 
printf("tm_wday: %d\n",result.tm_wday) ; 

} 
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return 0; 


} 


[RRR R KKK RRR AK KERR KER AKER KK EK AKER AK KEIRA KKK IKEA KEK A KE EA KE 
The output should be similar to: 
Tue 10/30/2001 10:59:10 AM 


tm_hour: 10 
tmmin: 59 
tmsec: 10 
tm_mon: 9 
tmmday: 30 
tmyear: 101 
tm_yday: 302 
tm_wday: 2 


KKK AK KKK KEKE AK KKK KKK KK KKK KKK KKK KKK KEK KK EKA KKK KKK EKER KK | 


Related Information 


strrchr() — Locate Last Occurrence of Character in String 
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Format 

#include <string.h> 

char *strrchr(const char *string, int c); 
Language Level: ANSI 


Description 


The strrchr() function finds the last occurrence of c (converted to a character) in 
string. The ending null character is considered part of the string. 


Return Value 


The strrchr() function returns a pointer to the last occurrence of c in string. If the 
given character is not found, a NULL pointer is returned. 


Example that uses strrchr() 


This example compares the use of strchr() and strrchr(). It searches the string 
for the first and last occurrence of p in the string. 
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#include <stdio.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
char buf[SIZE] = "computer program"; 
char * ptr; 
int ch = 'p'; 


/* This illustrates strchr */ 
ptr = strchr( buf, ch ); 
printf( "The first occurrence of %c in '%s' is '%s'\n", ch, buf, ptr ); 


/* This illustrates strrchr */ 
ptr = strrchr( buf, ch ); 
printf( "The last occurrence of %c in '%s' is '%s'\n", ch, buf, ptr ); 


} 


[KEKRKERKREKERERERK Output Should be similar tO: ***k*KKKKKKKKKKKK 
The first occurrence of p in ‘computer program’ is 'puter program' 
The last occurrence of p in ‘computer program' is 'program' 


*/ 


Related Information 


* wesrchar‘() 


strspn() —Find Offset of First Non-matching Character 
Format 
#include <string.h> 
size_t strspn(const char *stringl, const char *string2); 
Language Level: ANSI 
Thread Safe: YES 
Description 
The strspn() function finds the first occurrence of a character in string1 that is not 
contained in the set of characters that is specified by string2. The null character 
(\0) that ends string2 is not considered in the matching process. 


Return Value 


The strspn() function returns the index of the first character found. This value is 
equal to the length of the initial substring of string] that consists entirely of 
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characters from string2. If string] begins with a character not in string2, the 
strspn() function returns 0. If all the characters in string1 are found in string2, the 
length of string] is returned. 


Example that uses strspn() 


This example finds the first occurrence in the array string of a character that is not 
an a, b, or c. Because the string in this example is cabbage, the strspn() function 
returns 5, the length of the segment of cabbage before a character that is not an a, 
b, or c. 


#include <stdio.h> 
#include <string.h> 


int main(void) 
{ 
char * string 
char * source 
int index; 


"cabbage"; 
"abc" : 


index = strspn( string, "abc" ); 
printf( "The first %d characters of \"%s\" are found in \"%s\"\n", 
index, string, source ); 
} 


[KEKRKKEREKEREKER Output should be similar tO: *****KKKKKKKKKKKK 


The first 5 characters of "cabbage" are found in "abc" 
*/ 


Related Information 


strstr() — Locate Substring 
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Format 
#include <string.h> 
char *strstr(const char *stringl, const char *string2); 


Language Level: ANSI 


Thread Safe: YES 
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Description 


The strstr() function finds the first occurrence of string2 in string1. The function 
ignores the null character (\0) that ends string2 in the matching process. 


Return Value 


The strstr() function returns a pointer to the beginning of the first occurrence of 
string2 in string1. If string2 does not appear in string1, the strstr() function 
returns NULL. If string2 points to a string with zero length, the strstr() function 
returns string1. 


Example that uses strstr() 
This example locates the string “haystack” in the string "needle in a haystack". 


#include <string.h> 
#include <stdio.h> 


int main(void) 

{ 
char *stringl 
char *string2 
char *result; 


"needle in a haystack"; 
"haystack"; 


result = strstr(stringl,string2); 
/* Result = a pointer to "haystack" */ 
printf("%s\n", result); 


} 


[KEKRKRERKEKERERERK Output Should be similar tor ******KKKKKKKKEKK 


haystack 
*/ 


Related Information 


strtod() — Convert Character String to Double 


Format 
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#include <stdlib.h> 
double strtod(const char *nptr, char **endptr); 


Language Level: ANSI 

Thread Safe: YES 

Description 

The strtod() function converts a character string to a double-precision value. The 
parameter nptr points to a sequence of characters that can be interpreted as a 
numeric value of the type double. This function stops reading the string at the first 
character that it cannot recognize as part of a number. This character can be the 


null character at the end of the string. 


The strtod() function expects nptr to point to a string with the following form: 


be digits 
whitespace t- + LJ L vias! 
.—digits 


>< 


The first character that does not fit this form stops the scan. 


The behavior of this function is affected by the LC_NUMERIC category of the 
current locale. 


Return Value 


The strtod() function returns the value of the floating-point number, except when 
the representation causes an underflow or overflow. For an overflow, it returns 
-HUGE_VAL or +HUGE_VAL,; for an underflow, it returns 0. 


In both cases, errno is set to ERANGE, depending on the base of the value. If the 
string pointed to by nptr does not have the expected form, no conversion is 
performed and the value of nptr is stored in the object pointed to by endptr, 
provided that endptr is not a NULL pointer. 


The strtod() function does not fail if a character other than a digit follows an E or 
e read in as an exponent. For example, 100elf will be converted to the 
floating-point value 100.0. 

Example that uses strtod() 


This example converts the strings to a double value. It prints out the converted 
value and the substring that stopped the conversion. 
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#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 
char *string, *stopstring; 
double x; 


string = "3.1415926This stopped it"; 

x = strtod(string, &stopstring) ; 

printf("string = %s\n", string); 

printf("  strtod = %1f\n", x); 

printf(" Stopped scan at %s\n\n", stopstring); 


string = "100ergs"; 

x = strtod(string, &stopstring) ; 

printf("string = \"%s\"\n", string); 

printf("  strtod = %1f\n", x); 

printf(" Stopped scan at \"%s\"\n\n", stopstring); 
} 


[KEKRKEERKEKERERERK Output Should be similar tO: *****KKKKKKKKEKKK 


string = 3.1415926This stopped it 
strtod = 3.141593 
Stopped scan at This stopped it 


string = 100ergs 
strtod = 100.000000 
Stopped scan at ergs 
x/ 


Related Information 


strtok() — Tokenize String 
Format 
#include <string.h> 
char *strtok(char *stringl, const char *string2); 
Language Level: ANSI 
Description 


Thread Safe: NO. Use strtok_r() instead. 


The strtok() function reads string] as a series of zero or more tokens, and string2 
as the set of characters serving as delimiters of the tokens in string1. The tokens in 
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string] can be separated by one or more of the delimiters from string2. The tokens 
in string1 can be located by a series of calls to the strtok() function. 


In the first call to the strtok() function for a given string1, the strtok() function 
searches for the first token in string1, skipping over leading delimiters. A pointer to 
the first token is returned. 


When the strtok() function is called with a NULL string1 argument, the next 
token is read from a stored copy of the last non-null string] parameter. Each 
delimiter is replaced by a null character. The set of delimiters can vary from call to 
call, so string2 can take any value. Note that the initial value of string] is not 
preserved after the call to the strtok() function. 


Note that the strtok() function writes data into the buffer. The function should be 
passed to a non-critical buffer containing the string to be tokenized because the 
buffer will be damaged by the strtok() function. 


Return Value 


The first time the strtok() function is called, it returns a pointer to the first token 
in string1. In later calls with the same token string, the strtok() function returns a 
pointer to the next token in the string. A NULL pointer is returned when there are 
no more tokens. All tokens are null-ended. 


Note: The strtok() function uses an internal static pointer to point to the next 
token in the string being tokenized. A reentrant version of the strtok() 
function, strtok_r(), which does not use any internal static storage, can be 
used in place of the strtok() function. 


Example that uses strtok() 


Using a loop, this example gathers tokens, separated by commas, from a string 
until no tokens are left. The example prints the tokens, a string, of, and tokens. 


#include <stdio.h> 
#include <string.h> 


int main(void) 
{ 


char *token, «string = "a string, of, ,tokens\0,after null terminator"; 


/* the string pointed to by string is broken up into the tokens 


"a string", "of", "", and "tokens" ; the null terminator (\Q) 
is encountered and execution stops after the token "tokens" */ 
token = strtok(string, ","); 


do 
{ 


printf("token: %s\n", token); 


while (token = strtok(NULL, ",")); 
} 


[KEKRKRKEREKERERERE Output should be similar tO: *****KKKKEKKKKKKK 


token: a string 


token: of 
token: 

token: tokens 
x/ 
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Related Information 


strtok_r() — Tokenize String (Restartable) 


Format 


#include <string.h> 
char *strtok_r(char *string, const char *seps, 
char **lasts); 


Language Level: XPG4 

Thread Safe: YES. 

Description 

This function is the restartable version of strtok(). 


The strtok_r() function reads string as a series of zero or more tokens, and seps as 
the set of characters serving as delimiters of the tokens in string. The tokens in 
string can be separated by one or more of the delimiters from seps. The arguments 
lasts points to a user-provided pointer, which points to stored information 
necessary for the strtok_r() function to continue scanning the same string. 


In the first call to the strtok_r() function for a given null-ended string, it searches 
for the first token in string, skipping over leading delimiters. It returns a pointer to 
the first character of the first token, writes a null character into string immediately 
following the returned token, and updates the pointer to which Jasts points. 


To read the next token from string, call the strtok_r() function with a NULL string 
argument. This causes the strtok_r() function to search for the next token in the 
previous token string. Each delimiter is replaced in the original string is replaced 
by a null character, and the pointer to which Jasts points is updated. The set of 
delimiters in seps can vary from call to call, but lasts must remain unchanged from 
the previous call. When no tokens remain in string, a NULL pointer is returned. 


Return Value 

The first time the strtok_r() function is called, it returns a pointer to the first 
token in string. In later calls with the same token string, the strtok_r() function 
returns a pointer to the next token in the string. A NULL pointer is returned when 


there are no more tokens. All tokens are null-ended. 


Related Information 
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strtol() — strtoll() — Convert Character String to Long and Long Long 


Integer 


Format (strtol ()) 


#include <stdlib.h> 
long int strtol(const char *nptr, char **endptr, int base); 


Format (strtol]()) 


#include <stdlib.h> 
long long int strtoll(char «string, char **endptr, int base); 


Language Level: ANSI 

Thread Safe: YES 

Description 

The strtol() function converts a character string to a long integer value. The 
parameter nptr points to a sequence of characters that can be interpreted as a 
numeric value of type long int. 

The strtol1() function converts a character string to a long long integer value. 
The parameter nptr points to a sequence of characters that can be interpreted as a 


numeric value of type long long int. 


When you use these functions, the nptr parameter should point to a string with the 
following form: 


>>. 


digits >< 


whitespace | + 0 


If the base parameter is a value between 2 and 36, the subject sequence’s expected 
form is a sequence of letters and digits representing an integer whose radix is 
specified by the base parameter. This sequence is optionally preceded by a positive 
(+) or negative (-) sign. Letters from a to z inclusive (either upper or lower case) 
are ascribed the values 10 to 35; only letters whose ascribed values are less than 
that of the base parameter are permitted. If the base parameter has a value of 16, 
the characters 0x or 0X optionally precede the sequence of letters and digits, 
following the positive (+) or negative (-) sign, if present. 


If the value of the base parameter is 0, the string determines the base. After an 
optional leading sign a leading 0 indicates octal conversion, a leading 0x or 0X 
indicates hexadecimal conversion, and all other leading characters result in decimal 
conversion. 
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These functions scan the string up to the first character that is inconsistent with the 
base parameter. This character may be the null character ('\@') at the end of the 
string. Leading white-space characters are ignored, and an optional sign may 
precede the digits. 


If the value of the endptr parameter is not null a pointer, a pointer to the character 
that ended the scan is stored in the value pointed to by endptr. If a value cannot be 
formed, the value pointed to by endptr is set to the nptr parameter 


Return Value 


If base has an invalid value (less than 0, 1, or greater than 36), errno is set to 
EDOM and 0 is returned. The value pointed to by the endptr parameter is set to the 
value of the nptr parameter. 


If the value is outside the range of representable values, errno is set to ERANGE. 
If the value is positive, the strtol() function will return LONG_MAX, and the 
strtol1() function will return LONGLONG_MAx. If the value is negative, the 
strtol() function will return LONG_MIN, and the strtol1() function will return 
LONGLONG_MIN. 


If no characters are converted, the strtol1() function will set errno to EINVAL 
and 0 is returned. The strtol() function will return 0 but will not set errno to 
EINVAL. In both cases the value pointed to by endptr is set to the value of the nptr 
parameter. Upon successful completion, both functions return the converted value. 


Example that uses strtol () 


This example converts the strings to a long value. It prints out the converted value 
and the substring that stopped the conversion. 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 
char *string, *stopstring; 
long 13 
int bs; 


string = "10110134932"; 

printf("string = %s\n", string); 

for (bs = 2; bs <= 8; bs *= 2) 

{ 
1 = strtol(string, &stopstring, bs); 
printf("  strtol = %ld (base %d)\n", 1, bs); 
printf(" Stopped scan at %s\n\n", stopstring); 
} 

} 


[KEKRKEERKEKERERERE Output Should be similar tO: ***k*KKKKKKKKKKKK 
string = 10110134932 

strtol = 45 (base 2) 

Stopped scan at 34932 


strtol = 4423 (base 4) 
Stopped scan at 4932 


Related Information 


Chapter 2. Library Functions 363 


| strtoul() — strtoull() — Convert Character String to Unsigned Long and 
| Unsigned Long Long Integer 
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Format (strtoul ()) 


#include <stdlib.h> 
unsigned long int strtoul(const char *nptr, char **endptr, int base); 


Format (strtoul1 ()) 
#include <stdlib.h> 


unsigned long long int strtoull(char *string, char **endptr, int base); 
Language Level: ANSI 

Thread Safe: YES 

Description 

The strtoul() function converts a character string to an unsigned long integer 
value. The parameter nptr points to a sequence of characters that can be 
interpreted as a numeric value of type unsigned long int. 

The strtoull() function converts a character string to an unsigned long long 
integer value. The parameter nptr points to a sequence of characters that can be 


interpreted as a numeric value of type unsigned long long int. 


When you use these functions, the nptr parameter should point to a string with the 
following form: 


digits >< 


whitespace | + ) 


If the base parameter is a value between 2 and 36, the subject sequence’s expected 
form is a sequence of letters and digits representing an integer whose radix is 
specified by the base parameter. This sequence is optionally preceded by a positive 
(+) or negative (-) sign. Letters from a to z inclusive (either upper or lower case) 
are ascribed the values 10 to 35. Only letters whose ascribed values are less than 
that of the base parameter are permitted. If the base parameter has a value of 16 
the characters 0x or 0X optionally precede the sequence of letters and digits, 
following the positive (+) or negative (-) sign, if present. 
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If the value of the base parameter is 0, the string determines the base. After an 
optional leading sign a leading 0 indicates octal conversion, a leading 0x or 0X 
indicates hexadecimal conversion, and all other leading characters result in decimal 
conversion. 


These functions scan the string up to the first character that is inconsistent with the 
base parameter. This character may be the null character ('\0') at the end of the 
string. Leading white-space characters are ignored, and an optional sign may 
precede the digits. 


If the value of the endptr parameter is not null a pointer, a pointer to the character 
that ended the scan is stored in the value pointed to by endptr. If a value cannot 
be formed, the value pointed to by endptr is set to the nptr parameter. 


Return Value 


If base has an invalid value (less than 0, 1, or greater than 36), errno is set to 
EDOM and 0 is returned. The value pointed to by the endptr parameter is set to the 
value of the nptr parameter. 


If the value is outside the range of representable values, errno is set to ERANGE. 
The strtoul() function will return ULONG_MAX and the strtoul1() function 
will return ULONGLONG_MAX. 


If no characters are converted, the strtoul]() function will set errno to EINVAL 
and 0 is returned. The strtoul() function will return 0 but will not set errno to 
EINVAL. In both cases the value pointed to by endptr is set to the value of the nptr 
parameter. Upon successful completion, both functions return the converted value. 


Example that uses strtoul () 


This example converts the string to an unsigned long value. It prints out the 
converted value and the substring that stopped the conversion. 


#include <stdio.h> 
#include <stdlib.h> 


#define BASE 2 


int main(void) 

{ 
char *string, *stopstring; 
unsigned long ul; 


string = "1000e13 e"; 

printf("string = %s\n", string); 

ul = strtoul(string, &stopstring, BASE); 

printf("  strtoul = %ld (base %d)\n", ul, BASE); 

printf(" Stopped scan at %s\n\n", stopstring); 
} 


[KEKKRKKERKEKERERER Output Should be similar tO: ***kXKKKKKKKKEKKK 


string = 1000e13 e 
strtoul = 8 (base 2) 
Stopped scan at el3 e 

x/ 


Related Information 
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strxfrm() — Transform String 
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Format 
#include <string.h> 


size_t strxfrm(char *stringl, const char *string2, size_t count); 
Language Level: ANSI 
Thread Safe: YES 


Description 


The strxfrm() function transforms the string pointed to by string2 and places the 
result into the string pointed to by string1. The transformation is determined by the 
program’s current locale. The transformed string is not necessarily readable, but 
can be used with the strcmp ()] or ee 


The behavior of this function is affected by the LC_COLLATE category of the 
current locale. 


Return Value 

The strxfrm() function returns the length of the transformed string, excluding the 
ending null character. If the returned value is greater than or equal to count, the 
contents of the transformed string are indeterminate. 

If strxfrm() is unsuccessful, errno is changed. The value of errno may be set to 
EINVAL (the string] or string2 arguments contain characters which are not 
available in the current locale). 


Example that uses strxfrm() 


This example prompts the user to enter a string of characters, then uses 
strxfrm()to transform the string and return its length. 
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#include <stdio.h> 
#include <string.h> 


int main(void) 

{ 
char *stringl, buffer[80]; 
int length; 


printf("Type in a string of characters.\n "); 

stringl = gets(buffer) ; 

length = strxfrm(NULL, stringl, 0); 

printf("You would need a %d element array to hold the string\n", length); 
printf("\n\n%s\n\n transformed according",string1); 

printf(" to this program's locale. \n"); 


} 


Related Information 


swprintf() — Format and Write Wide Characters to Buffer 


Format 


#include <wchar.h> 
int swprintf(wchar_t *wcsbuffer, size_t n, 
const wchar_t *format, argument-list); 


Language Level: ANSI 
Thread Safe: YES 
Description 


The swprintf() function formats and stores a series of wide characters and values 
into the wide-character buffer wesbuffer. The swprintf () function is equivalent to 
the sprintf() function, except that it operates on wide characters. 


The value n specifies the maximum number of wide characters to be written, 

including the ending null character. The swprintf() function converts each entry in 

the argument-list according to the corresponding wide-character format specifier in 
format. The format has the same form and function as the format string for the 
printf() function, with the following exceptions: 

* %c (without an | prefix) converts a character argument to wchar_t, as if by 
calling the mbtowc() function. 

* %lc and %C copy a wchar_t to wchar_t. %#lc and %#C are equivalent to %lc 
and %C, respectively. 

* %s (without an | prefix) converts an array of multibyte characters to an array of 
wchar_t, as if by calling the mbstowcs() function. The array is written up to, but 
not including, the ending null character, unless the precision specifies a shorter 
output. 
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* %ls and %S copy an array of wchar_t (no conversion). The array is written up 
to, but not including, the ending NULL character, unless the precision specifies a 
shorter output. %#ls and %#S are equivalent to %ls and %S, respectively. 


Width and precision always are wide characters. 


When the program is compiled with LOCALETYPE(*LOCALEUCS2) and 
SYSIFCOPT(*IFSIO), the wide characters that are written by this function are 
UNICODE characters, and the inputs for %lc and %ls are_assumed _to be 
UNICODE characters. To view UNICODE examples, see 


A null wide character is added to the end of the wide characters written; the null 
wide character is not counted as part of the returned value. If copying takes place 
between objects that overlap, the behavior is undefined. 


In extended mode, the swprintf() function also converts floating-point values of 
NaN and infinity to the strings "NAN" or “nan” and "INFINITY" or “infinity”. The 
case and sign of the string is determined by the format specifiers. 


Note: This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) and SYSIFCOPT(*IFSIO) is specified on the 
compilation command. 


Return Value 


The swprintf() function returns the number of wide characters that are written in 
the array, not counting the ending null wide character. 


The value of errno may be set to EINVAL, invalid argument. 
Example that uses swprintf() 


This example uses the swprintf() function to format and print several values to 
buffer. 


#include <wchar.h> 
#include <stdio.h> 


#define BUF_SIZE 100 


int main(void) 

{ 
wchar_t wcsbuf[BUF_SIZE]; 
wchar_t wstring[] = L"ABCDE"; 
int num; 


num = swprintf(wcsbuf, BUF_SIZE, L"%s", "xyz"); 

num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%ls", wstring); 
num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%i", 100); 
printf("The array wcsbuf contains: \"%1s\"\n", wcsbuf); 

return 0; 


[BRK RK KKK KKK AKER AKER A KKK IKK A KKK IKKE KK KER AKEKA KKK KK EAR KERR 
The output should be similar to : 


The array wcsbuf contains: "xyzABCDE100" 


KKK KKK KKK KKK KKK RK KKK KKK A KKK KKK A KKK KKK KKK AK KKK KK EAR ERK KER | 
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Related Information 


swscanf() — Read Wide Character Data 


Format 

#include <wchar.h> 

int swscanf(const wchar_t *buffer, const wchar_t *format, argument-list); 
Language Level: ANSI 

Thread Safe: YES 

Description 

The swscanf() function is equivalent of the fwscanf() function, except that the 
argument buffer specifies a wide string from which the input is to be obtained, 
rather than from a stream. Reaching the end of the wide string is equivalent to 
encountering end-of-file for the fwscanf() function. 

Return Value 

The swscanf() function returns the number of fields that were successfully 
converted and assigned. The return value does not include fields that were read 
but not assigned. The return value is EOF when the end of the string is 
encountered before anything is converted. 

The value of errno may be set EINVAL, invalid argument. 


Example that uses swscanf() 


This example uses the swscanf() function to read various data from the string 
Itokenstring, and then displays that data. 
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#include <wchar.h> 
#include <stdio.h> 


wchar_t *ltokenstring = L"15 12 14"; 
int is; 

float fp; 

char s[10]; 

char c; 


int main(void) 
{ 


/* Input various data */ 


swscanf(ltokenstring, L"%s %c%d%f", s, &c, &i, &fp); 


/* If there were no space between %s and %c, x/ 
/* swscanf would read the first character following */ 
/* the string, which is a blank space. x/ 


printf("string = %s\n",s); 
printf("character = %c\n",c); 
printf("integer = %d\n",i); 
printf("floating-point number = %f\n",fp); 


} 


Related Information 


system() — Execute a Command 


Format 
#include <stdlib.h> 
int system(const char *string); 


Language Level: ANSI 


Thread Safe: YES. However, the CL command processor and all CL commands are 
NOT thread safe. Use this function with caution. 


Description 


The system() function passes the given string to the CL command processor for 
processing. 


Return Value 
If passed a non-NULL pointer to a string, the system() function passes the 


argument to the CL command processor. The system() function returns zero if the 
command is successful. If passed a NULL pointer to a string, system() returns -1, 
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and the command processor is not called. If the command fails, system() returns 1. 
If the system() function fails, the global variable EXCP_MSGID in <stddef.h> is 
set with the exception message ID. 


Example that uses system() 


#include <stdlib.h> 
int main(void) 
{ 


int result; 


/* A data area is created, displayed and deleted: ~*/ 


result = system("CRTDTAARA QTEMP/TEST TYPE(*CHAR) VALUE('Test')"); 
result = system("DSPDTAARA TEST"); 
result = system("DLTDTAARA TEST"); 


} 


Related Information 


tan() — Calculate Tangent 
Format 
#include <math.h> 
double tan(double x); 
Language Level: ANSI 
Description 
The tan() function calculates the tangent of x, where x is expressed in radians. If x 
is too large, a partial loss of significance in the result can occur and sets errno to 
ERANGE. The value of errno may also be set to EDOM. 
Return Value 
The tan() function returns the value of the tangent of x. 


Example that uses tan() 


This example computes x as the tangent of m/4. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 
double pi, x; 


pi = 3.1415926; 
x = tan(pi/4.0); 


printf("tan( %1f ) is %1f\n", pi/4, x); 
} 


[KEKRKKRRKKERKKERKE Output Should be similar tO: ****KKKKKKKKKKKK 


tan( 0.785398 ) is 1.000000 
*/ 


Related Information 


tanh() — Calculate Hyperbolic Tangent 
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Format 

#include <math.h> 
double tanh(double x); 
Language Level: ANSI 


Description 


The tanh() function calculates the hyperbolic tangent of x, where x is expressed in 
radians. 


Return Value 


The tanh() function returns the value of the hyperbolic tangent of x. The result of 
tanh() cannot have a range error. 


Example that uses tanh() 


This example computes x as the hyperbolic tangent of m/4. 
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#include <math.h> 
#include <stdio.h> 


int main(void) 
double pi, x; 


pi = 3.1415926; 
x = tanh(pi/4); 


printf("tanh( %1f ) = %1f\n", pi/4, x); 
} 


[EK RKERKRKKERKEREKE Output should be similar tO: ***kKKxKKKKKKEKKK 


tanh( 0.785398 ) = 0.655794 
*/ 


Related Information 


time() — Determine Current Time 


Format 


#include <time.h> 
time_t time(time_t *timeptr); 


Language Level: ANSI 
Description 
The time() function determines the current calendar time, in seconds. 


Note: 

* Calendar time is the number of seconds that have elapsed since EPOCH, 
which is 00:00:00, January 1, 1970 Universal Coordinate Time (UTC). 

* On the iSeries system, the time function uses the QUTCOFFSET system 
value for calculating UTC. The QUTCOFFSET value specifies the 
difference in hours and minutes between UTC, also known as Greenwich 
mean time, and the current system time. You can override the 
QUTCOFFSET value by specifying the TZDIFF and TZNAME category of 
the current locale. 


Return Value 
The time() function returns the current calendar time. The return value is also 
stored in the location that is given by timeptr. If timeptr is NULL, the return value 


is not stored. If the calendar time is not available, the value (time_t)(-1) is returned. 


Chapter 2. Library Functions 373 


Example that uses time() 


This example gets the time and assigns it to /time. The ctime() function then 
converts the number of seconds to the current date and time. This example then 
prints a message giving the current time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 
time_t ltime; 
if(time(localtime()) == -1) 
printf("Calendar time not available.\n"); 
exit(1); 

} 


} 


[KEKRKKRRKKEKEKKERKE Output Should be similar tO: ****KKKKKKKKKKKK 


printf("The time is %s\n", ctime(localtime())); 


The time is Mon Mar 22 19:01:41 1993 
x/ 


Related Information 


tmpfile() — Create Temporary File 
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Format 

#include <stdio.h> 
FILE *tmpfile(void); 
Language Level: ANSI 


Description 


The tmpfile() function creates a temporary binary file. The file is automatically 
removed when it is closed or when the program is ended. 


The tmpfile() function opens the temporary file in wb+ mode. 


Return Value 
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The tmpfile() function returns a stream pointer, if successful. If it cannot open the 
file, it returns a NULL pointer. On normal end (exit()), these temporary files are 
removed. 


On the iSeries Data Management system, the tmpfile() function creates a new file 
that is named QTEMP/QACXxxxx. If you specify the SYSIFCOPT(*IFSIO) option 
on the compilation command, the tmpfile() function creates a new file that is 
named /tmp/QACxXaaaaaaa. At the end of the job, the file that is created with the 
filename from the tmpfile() function is discarded. You can use the remove() 
function to remove files. 


Example that uses tmpfile() 


This example creates a temporary file, and if successful, writes tmpstring to it. At 
program end, the file is removed. 


#include <stdio.h> 


FILE «stream; 
char tmpstring[ ] = "This is the string to be temporarily written"; 


int main(void) 


{ 
if((stream = tmpfile( )) == NULL) 
perror("Cannot make a temporary file"); 
else 
fprintf(stream, "%s", tmpstring); 
} 


Related Information 


tmpnam() — Produce Temporary File Name 


Format 


#include <stdio.h> 
char *tmpnam(char *string); 


Language Level: ANSI 
Thread Safe: YES. However, using tmpnam(NULL) is NOT thread safe. 
Description 


The tmpnam() function produces a valid file name that is not the same as the name 
of any existing file. It stores this name in string. If string is NULL, the tmpnam() 
function leaves the result in an internal static buffer. Any subsequent calls destroy 
this value. If string is not NULL, it must point to an array of at least L_tmpnam 
bytes. The value of L_tmpnam is defined in <stdio.h>. 


The tmpnam() function produces a different name each time it is called within an 
activation group up to at least TMP_MAX names. For ILE C, TMP_MAX is 32 767. 
This is a theoretical limit; the actual number of files that can be opened at the same 
time depends on the available space in the system. 


Return Value 
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The tmpnam() function returns a pointer to the name. If it cannot create a unique 
name then it returns NULL. 


Example that uses tmpnam() 
This example calls tmpnam() to produce a valid file name. 


#include <stdio.h> 


int main(void) 
{ 
char *namel; 
if ((namel = tmpnam(NULL)) !=NULL) 
printf("%s can be used as a file name.\n", namel); 
else printf("Cannot create a unique file name\n"); 


} 


Related Information 


toascii() — Convert Character 
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Format 

#include <ctype.h> 

int toascii(int c); 

Language Level: XPG4 

Description 

The toascii() function determines to what character c would be mapped to in a 
7—-bit US-ASCII locale and returns the corresponding EBCDIC encoding in the 
current locale. 


Return Value 


The toascii() function maps the character c according to a 7-bit US-ASCII locale 
and returns the corresponding EBCDIC encoding in the current locale. 


Example that uses toascii() 


This example prints EBCDIC encodings of the 7—bit US-ASCII characters 0x7c to 
0x82 are mapped to by toascii(). 
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#include <stdio.h> 
#include <ctype.h> 


void main(void) 
{ 


int ch; 
for (ch=0x7c; ch<=0x82; cht+) { 
printf("toascii(%#04x) = %c\n", ch, toascii(ch)); 


} 
} 


[KxkKKKKKKKKKKKEEKANG the output SHOU Der xXXKKKKKKKKKKKEKKKKEKKE KKK KKK KKK 


toascii(@x7c) = @ 
toascii(@x7d) = ' 
toascii(@x7e) = = 
toascii(O@x7f) = " 
toascii(@x80) = X 
toascii(@x81) = a 
toascii(@x82) = b 


KA KK RAK KKK KIRKE KKK KKK AK KAKA K KIBAKI AREA EREKER EK | 


Related Information 


tolower() — toupper() — Convert Character Case 


Format 


#include <ctype.h> 
int tolower(int C); 
int toupper(int c); 


Language Level: ANSI 
Description 


The tolower() function converts the uppercase letter C to the corresponding 
lowercase letter. 


The toupper() function converts the lowercase letter c to the corresponding 
uppercase letter. 


Return Value 


Both functions return the converted character. If the character c does not have a 
corresponding lowercase or uppercase character, the functions return c unchanged. 


Note: This function is locale sensitive. 
Example that uses toupper() and tolower() 


This example uses the toupper() and tolower() functions to change characters 
between code 0 and code 7f. 
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#include <stdio.h> 
#include <ctype.h> 


int main(void) 
int ch; 
for (ch = 0; ch <= Ox7f; ch++) 
{ 
printf ("toupper=%#04x\n", toupper(ch)); 
printf ("tolower=%#04x\n", tolower(ch)); 
putchar('\n'); 


} 


Related Information 


towctrans() — Translate Wide Character 
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Format 

#include <wctype.h> 

wint_t towctrans(wint_t wc, wctrans_t desc); 

Language Level: ANSI 

Description 

The towctrans() function maps the wide character we using the mapping that is 
described by desc. The current setting of the LC_CTYPE category shall be the same 
as the one used during the call to the towctrans() function that returned the value 


desc. 


A towctrans(wc, wctrans("tolower")) behaves in the same way as the call to the 
wide-character, case-mapping function towlower(). 


A towctrans(wc, wctrans("toupper")) behaves in the same way as the call to the 
wide-character, case-mapping function towupper(). 


Return Value 


The towctrans() function returns the mapped value of we using the mapping that 
is described by desc. 


Example that uses towctrans() 
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#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <wchar.h> 
#include <wctype.h> 


int main() 

{ 
char *alpha = "abcdefghijkIlmnopqrstuvwxyz"; 
char *tocase[2] = {"toupper", "tolower"}; 
wchar_t *wcalpha; 
int i, js 
size_t alphalen; 


alphalen = strlen(alpha)+1; 
wealpha = (wchar_t *)malloc(sizeof(wchar_t)*alphalen) ; 


mbstowcs(wcalpha, alpha, 2*alphalen); 

for (i=0; i<2; ++i) { 
printf("Input string: %1s\n", wcalpha); 
for (j=0; j 
for (j=0; j 


Related Information 


towlower() —towupper() — Convert Wide Character Case 


Format 


#include <wctype.h> 
wint_t towlower(wint_t wc); 
wint_t towupper(wint_t wc); 


Thread Safe: YES. 

Description 

The towupper() function converts the lowercase character we to the corresponding 
uppercase letter. The towlower() function converts the uppercase character we to 


the corresponding lowercase letter. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 

If we is a wide character for which iswupper() (or iswlower()) is true and there is 
a corresponding wide character for which iswlower() (or iswupper()) is true, 
towlower() (or towupper()) returns the corresponding wide character. Otherwise, 
the argument is returned unchanged. 


Example that uses towlower() and towupper() 


This example uses towlower() and towupper() to convert characters between 0 and 
Ox7f. 
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#include <wctype.h> 
#include <stdio.h> 


int main(void) 
wint_t w_ch; 


for (w_ch = 0; wch <= Oxff; w_cht+) { 
printf ("towupper : %#04x %#04x, ", w_ch, towupper(w_ch)); 
printf ("towlower : %#04x %#04x\n", w_ch, towlower(w_ch)); 
} 
return 0; 
[EKA KKK KEKE AK KER KKK AKER KK AK KEK KEIR KEK AKAIKE AK KEK AKAIKE AKER EK 


The output should be similar to: 


towupper : Qxcl Oxcl, towlower : Oxcl 0x81 
towupper : Qxc2 Oxc2, towlower : Oxc2 0x82 
towupper : Qxc3 0xc3, towlower : 0xc3 0x83 
towupper : Qxc4 Oxc4, towlower : Oxc4 0x84 
towupper : @xc5 Oxc5, towlower : 0xc5 0x85 


towupper : Qx81 Oxcl, towlower : 0x81 0x81 
towupper : x82 Oxc2, towlower : 0x82 0x82 
towupper : 0x83 0xc3, towlower : 0x83 0x83 
towupper : 0x84 Oxc4, towlower : 0x84 0x84 
towupper : @x85 0xc5, towlower : 0x85 0x85 


KKK KKK KKK KEKE KK KKK KKK KK KKK KKK KKK KK KIKI KK KKK AKA KHER AEE KARE KK | 


} 


Related Information 


_ultoa - Convert Unsigned Long Integer to String 
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Format 

#include <stdlib.h> 

char *_ultoa(unsigned long value, char *string, int radix); 

Note: The _ultoa function is supported only for C++, not for C. 

Language Level: Extension 

Description 

_ultoa converts the digits of the given unsigned long value to a character string 

that ends with a null character and stores the result in string. The radix argument 

specifies the base of value; it must be in the range 2 to 36. 

Note: The space allocated for string must be large enough to hold the returned 
string. The function can return up to 33 bytes including the null character 
(\0). 


Return Value 


_ultoa returns a pointer to string. There is no error return value. 
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Example that uses _ultoa() 


This example converts the integer value 255 to a decimal, binary, and hexidecimal 
representation. 


#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 
char buffer[35]; 
char *p; 
p = _ultoa(255UL, buffer, 10); 
printf("The result of _ultoa(255) with radix of 10 is %s\n", p); 
p = _ultoa(255UL, buffer, 2); 
printf("The result of _ultoa(255) with radix of 2\n is %s\n", p); 
p = _ultoa(255UL, buffer, 16); 
printf("The result of _ultoa(255) with radix of 16 is %s\n", p); 
return 0; 


} 


The output should be: 


The result of _ultoa(255) with radix of 10 is 255 
The result of _ultoa(255) with radix of 2 

is 11111111 
The result of _ultoa(255) with radix of 16 is ff 


Related Information 


¢ <stdlib.h> 


ungetc() — Push Character onto Input Stream 


Format 
#include <stdio.h> 


int ungetc(int c, FILE *stream); 

Language Level: ANSI 

Description 

The ungetc() function pushes the unsigned character c back onto the given input 
stream. However, only one consecutive character is guaranteed to be pushed back 
onto the input stream if you call ungetc()consecutively. The stream must be open 
for reading. A subsequent read operation on the stream starts with c. The character 


c cannot be the EOF character. 


Characters placed on the stream by ungetc() will be erased if fseek(), fsetpos(), 
rewind(), or fflush() is called before the character is read from the stream. 


Return Value 


The ungetc() function returns the integer argument c converted to an unsigned 
char, or EOF if c cannot be pushed back. 


The value of errno may be set to: 


Value Meaning 
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ENOTREAD 
The file is not open for read operations. 


EIOERROR 
A non-recoverable I/O error occurred. 


EIORECERR 
A recoverable I/O error occurred. 


The ungetc() function is not supported for files opened with type=record. 
Example that uses ungetc() 


In this example, the while statement reads decimal digits from an input data 
stream by using arithmetic statements to compose the numeric values of the 
numbers as it reads them. When a non-digit character appears before the end of 
the file, ungetc() replaces it in the input stream so that later input functions can 
process it. 


#include <stdio.h> 
#include <ctype.h> 


int main(void) 
{ 
FILE «stream; 
int ch; 
unsigned int result = 0; 
while ((ch = getc(stream)) != EOF && isdigit(ch)) 
result = result * 10 + ch - '0'; 
if (ch != EOF) 
ungetc(ch,stream) ; 
/* Put the nondigit character back */ 
printf("The result is: %d\n", result); 
if ((ch = getc(stream)) != EOF) 
printf("The character is: %c\n", ch); 


} 


Related Information 


ungetwc() — Push Wide Character onto Input Stream 
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Format 


#include <wchar.h> 
#include <stdio.h> 
wint_t ungetwc(wint_t wc, FILE *stream); 


Language Level: ANSI 


Description 
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The ungetwc() function pushes the wide character we back onto the input stream. 
The pushed-back wide characters will be returned by subsequent reads on that 
stream in the reverse order of their pushing. A successful intervening call (on the 
stream) to a file positioning function (fseek(), fsetpos(), or rewind()) discards 
any pushed-back wide characters for the stream. The external storage 
corresponding to the stream is unchanged. There is always at least one wide 
character of push-back. If the value of we is WEOF, the operation fails and the 
input stream is unchanged. 


A successful call to the ungetwc() function clears the EOF indicator for the stream. 
The value of the file position indicator for the stream after reading or discarding 
all pushed-back wide characters is the same as it was before the wide characters 
were pushed back. However, only one consecutive wide character is guaranteed to 
be pushed back onto the input stream if you call ungetwc() consecutively. 


For a text stream, the file position indicator is backed up by one wide character. 
This affects the ftel1(), fflush(), fseek() (with SEEK_CUR), and 

fgetpos () function. For a binary stream, the position indicator is unspecified until 
all characters are read or discarded, unless the last character is pushed back, in 
which case the file position indicator is backed up by one wide character. This 
affects the ftell(), fseek() (with SEEK_CUR), fgetpos(), and fflush() function. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


The ungetwc() function returns the wide character pushed back after conversion, 
or WEOF if the operation fails. 


Example that uses ungetwc() 


#include <wchar.h> 
#include <wctype.h> 
#include <stdio.h> 
#include <stdlib.h> 


int main(void) 


{ 


FILE «stream; 
wint_t WC3 
wint_t we2; 


unsigned int result = 0; 


if (NULL == (stream = fopen("ungetwc.dat", "r+"))) { 
printf("Unable to open file.\n"); 
exit (EXIT_FAILURE) ; 

} 


while (WEOF != (wc = fgetwc(stream)) && iswdigit(wc)) 
result = result * 10 + we - L'0'; 


if (WEOF != wc) 
ungetwc(wc, stream); /* Push the nondigit wide character back */ 


/* get the pushed back character «/ 
if (WEOF != (wc2 = fgetwc(stream))) { 
if (we != we2) { 
printf("Subsequent fgetwc does not get the pushed back character.\n"); 
exit (EXIT_FAILURE) ; 
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printf("The digits read are '%i'\n" 
"The character being pushed back is '%lc'", result, wc2); 
} 


return 0; 


[BRK RKKRAKK RIKER AKER AKIRA KK AKKEA KKK KKK IKE I KKK IKKE IKKE IKKE KARE RARER KK 
Assuming the file ungetwc.dat contains: 


12345ABCDE67890XYZ 
The output should be similar to : 
The digits read are '12345' 


The character being pushed back is 'A' 
KKK KA KKK KK KAKA KEIRA KK AK KEI KKK KKK IKEA KKK IKEA KK AAR EK ARERR EEK | 


} 


Related Information 


va_arg() — va_end() — va_start() — Access Function Arguments 


384 


Format 

#include <stdarg.h> 

var_type va_arg(va_list arg_ptr, var_type); 
void va_end(va_list arg_ptr); 

void va_start(va_list arg_ptr, variable_name) ; 


Language Level: ANSI 
Description 


The va_arg(), va_end(), and va_start() functions access the arguments to a 
function when it takes a fixed number of required arguments and a variable 
number of optional arguments. You declare required arguments as ordinary 
parameters to the function and access the arguments through the parameter names. 


va_start() initializes the arg_ptr pointer for subsequent calls to va_arg() and 
va_end(). 


The argument variable_name is the identifier of the rightmost named parameter in 
the parameter list (preceding , ...). Its type must be one of int, long, decimal, 
double, struct, union, or pointer, or a typedef of one of these types. Use va_start() 
before va_arg(). Corresponding va_start() and va_end() macros must be in the 
same function. 


The va_arg() function retrieves a value of the given var_type from the location 
given by arg_ptr, and increases arg_ptr to point to the next argument in the list. The 
va_arg() function can retrieve arguments from the list any number of times within 
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the function. The var_type argument must be one of int, long, decimal, double, 
struct, union, or pointer, or a typedef of one of these types. 


The va_end() function is needed to indicate the end of parameter scanning. 
Return Value 


The va_arg() function returns the current argument. The va_end and va_start() 
functions do not return a value. 


Example that uses va_arg() — va_end() — va_start() 


This example passes a variable number of arguments to a function, stores each 
argument in an array, and prints each argument. 


#include <stdio.h> 
#include <stdarg.h> 


int vout(int max, ...)3 


int main(void) 
{ 
vout(3, "Sat", "Sun", "Mon"); 
printf("\n"); 
vout(5, "Mon", "Tues", "Wed", "Thurs", "Fri"); 


} 


int vout(int max, ...) 
{ 
va_list arg_ptr; 
int args = 0; 
char *days[7]; 


va_start(arg_ptr, max); 
while(args < max) 


days[args] = va_arg(arg_ptr, char *); 
printf("Day: %s \n", days[args++]); 
} 

va_end(arg_ptr); 


} 


[EK RKERKEKKRRKERKEKE Output Should be similar tO: ****kKxKKKKKKEKKK 


Day: Sat 
Day: Sun 
Day: Mon 
Day: Mon 
Day: Tues 
Day: Wed 
Day: Thurs 
Day: Fri 
x/ 


Related Information 
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vfprintf() — Print Argument Data to Stream 


386 


Format 


#include <stdarg.h> 
#include <stdio.h> 
int vfprintf(FILE *stream, const char «format, va_list arg_ptr); 


Language Level: ANSI 

Description 

The vfprintf() function formats and writes a series of characters and values to the 
output stream. The vfprintf() function works just like the fprintf() function, 
except that arg_ptr points to a list of arguments whose number can_vary from call 
to call in the program. These arguments should be initialized by wa_ for each 
call. In contrast, the fprintf() function can have a list of arguments, but the 
number of arguments in that list is fixed when you compile the program. 

The vfprintf() function converts each entry in the argument list according to the 
corresponding format specifier in format. The format has the same form and 
function as the format string for the printf() function. 


Return Value 


If successful, vfprintf() returns the number of bytes written to stream. If an error 
occurs, the function returns a negative value. 


Example that uses vfprintf () 


This example prints out a variable number of strings to the file myfile. 
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#include <stdarg.h> 
#include <stdio.h> 


void vout(FILE «stream, char «fmt, ...); 
char fmtl [] = "%s %s %s\n"3; 


int main(void) 
{ 
FILE «stream; 
stream = fopen("mylib/myfile", "w"); 


vout(stream, fmtl, "Sat", "Sun", "Mon"); 


} 


void vout(FILE «stream, char *fmt, ...) 


{ 


va_list arg_ptr; 
va_start(arg_ptr, fmt); 
vfprintf(stream, fmt, arg_ptr); 
va_end(arg_ptr); 

} 


[EK RKRRKKKRRKEREKE Output Should be similar tO: ****KKXKKKKKKEKKK 


Sat Sun Mon 
x/ 


Related Information 


vfwprintf() — Format Argument Data as Wide Characters and Write to a 


Stream 


Format 


#include <stdarg.h> 
#include <stdio.h> 
#include <wchar.h> 
int vfwprintf(FILE «stream, const wchar_t *format, va_list arg); 


Language Level: ANSI 

Description 

The vfwprintf() function is equivalent to the fwprintf() function, except that the 
variable argument list is replaced by arg, which the va_start macro (and possibly 


subsequent va_arg calls) will have initialized. The vfwprintf() function does not 
invoke the va_end macro. 
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Because the functions vfwprintf(), vswprintf(), and vwprintf()invoke the va_arg 
macro, the value of arg after the return is unspecified. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) are specified on the compilation command. 


Return Value 


The vfwprintf() function returns the number of wide characters transmitted. If an 
output error occurred, it returns a negative value. 


Example that uses vfwprintf () 


This example prints the wide character a to a file.. The printing is done from the 
vout() function, which takes a variable number of arguments and uses 
vfwprintf() to print them to a file. 

#include <wchar.h> 


#include <stdarg.h> 
#include <locale.h> 


void vout (FILE *stream, wchar_t *fmt, ...); 
const char ifs_path [] = "tmp/myfile"; 
int main(void) { 


FILE xstream; 
wehar_t format [] = L"%1c"; 


setlocale(LC_ALL, "POSIX"); 

if ((stream = fopen (ifs_path, "w")) == NULL) { 
printf("Could not open file.\n"); 
return (-1); 

} 

vout (stream, format, L'a'); 

fclose (stream) ; 


[KERR KKK A KKK KKK KKK KKK KKK KER AK KAKA AKER KK 
The contents of output file tmp/myfile.dat should 
be a wide char 'a' which in the "POSIX" locale 
is 'Q0081'x. 

*/ 


return (0); 


} 


void vout (FILE *stream, wchar_t *fmt, ...) 
{ 

va_list arg_ptr; 

va_start (arg_ptr, fmt); 

vfwprintf (stream, fmt, arg_ptr); 

va_end (arg_ptr); 


} 


Related Information 
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vprintf() — Print Argument Data 


Format 


#include <stdarg.h> 
#include <stdio.h> 
int vprintf(const char «format, va_list arg_ptr); 


Language Level: ANSI 

Description 

The vprintf() function formats and prints a series of characters and values to 
stdout. The vprintf() function works just like the printf () function, except that 
arg_ptr points to a list of arguments whose number can vary from call to call in the 
program. These arguments should be initialized by kea_starl for each call. In 
contrast, the printf() function can have a list of arguments, but the number of 
arguments in that list is fixed when you compile the program. 

The vprintf() function converts each entry in the argument list according to the 
corresponding format specifier in format. The format has the same form and 
function as the format string for the printf() function. 

Return Value 

If successful, the vprintf() function returns the number of bytes written to stdout. 
If an error occurs, the vprintf() function returns a negative value. The value of 
errno may be set to ETRUNC. 

Example that uses vprintf() 


This example prints out a variable number of strings to stdout. 
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#include <stdarg.h> 
#include <stdio.h> 


void vout(char «fmt, ...)3 
char fmtl [] = "%s %s %s %S  %s \n"s 


int main(void) 
{ 
FILE «stream; 
stream = fopen("mylib/myfile", "w"); 


vout(fmtl, "Mon", "Tues", "Wed", "Thurs", "Fri"); 


} 


void vout(char «fmt, ...) 


{ 


va_list arg_ptr; 
va_start(arg_ptr, fmt); 
vprintf(fmt, arg_ptr); 
va_end(arg_ ptr); 


} 


[KEKRKKRRKKERKKERKE Output Should be similar tO: ***kKKKKKKKKKEKKK 


Mon Tues Wed Thurs Fri 
x/ 


Related Information 


| vsnprintf() — Print Argument Data to Buffer 


390 


Format 


#include <stdarg.h> 
#include <stdio.h> 
int vsnprintf(char *target-string, size_t n, const char *format, va_list arg ptr); 


Language Level: ANSI 
Description 


The vsnprintf() function formats and stores a series of characters and values in 
the buffer target-string. The vsnprintf() function works just like the snprintf () 
function, except that arg_ptr points to a list of arguments whose number can vary 
from call to call in the program. These arguments should be initialized by the 
va_start function for each call. In contrast, the snprintf() function can have a list 
of arguments, but the number of arguments in that list is fixed when you compile 
the program. 


The vsnprintf() function converts each entry in the argument list according to the 
corresponding format specifier in format. The format has the same form and 
function as the format string for the printf() function. 
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Return Value 


The vsnprintf() function returns the number of bytes that are written in the array, 
not counting the ending null character. 


Example that uses vsnprintf () 


This example assigns a variable number of strings to string and prints the resultant 
string. 

#include <stdarg.h> 

#include <stdio.h> 


void vout(char «string, char «fmt, ...); 
char fmtl [] = "%s %s %s\n"3 


int main(void) 
{ 
char string[100]; 


vout(string, fmtl, "Sat", "Sun", "Mon"); 
printf("The string is: %s\n", string); 


void vout(char «string, char «fmt, ...) 


{ 


va_list arg_ptr; 
va_start(arg_ptr, fmt); 
vsnprintf(string, 8, fmt, arg_ptr); 
va_end(arg_ptr); 

} 


[KEK RKKRKRKKERKEREKE Output should be similar to: *******KKKKKKKKKK 


The string is: Sat Su 
*/ 


Related Information 


vsprintf() — Print Argument Data to Buffer 


Format 


#include <stdarg.h> 
#include <stdio.h> 
int vsprintf(char *target-string, const char «format, va_list arg ptr); 


Language Level: ANSI 


Description 
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The vsprintf() function formats and stores a series of characters and values in the 
buffer target-string. The vsprintf() function works just like 

except that arg_ptr points to a list of arguments whose number can vary from call 
to call in the program. These arguments should be initialized by the va_start 
function for each call. In contrast, the sprintf() function can have a list of 
arguments, but the number of arguments in that list is fixed when you compile the 
program. 


The vsprintf() function converts each entry in the argument list according to the 
corresponding format specifier in format. The format has the same form and 
function as the format string for the printf() function. 


Return Value 


If successful, the vsprintf() function returns the number of bytes written to 
target-string. If an error occurs, the vsprintf() function returns a negative value. 


Example that uses vsprintf() 


This example assigns a variable number of strings to string and prints the resultant 
string. 


#include <stdarg.h> 
#include <stdio.h> 


void vout(char «string, char «fmt, ...); 
char fmtl [] = "%s %s %s\n"3; 


int main(void) 
char string[100]; 
vout(string, fmtl, "Sat", "Sun", "Mon"); 
printf("The string is: %s\n", string); 
} 
void vout(char «string, char «fmt, ...) 
{ 
va_list arg_ptr; 
va_start(arg_ptr, fmt); 
vsprintf(string, fmt, arg_ptr); 
va_end(arg_ptr); 
} 


[#EKRKERRKEERKREREE Output should be similar tO: *****KKKKKKKKKKK 


The string is: Sat Sun Mon 
*/ 


Related Information 
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vswprintf() — Format and Write Wide Characters to Buffer 


Format 


#include <stdarg.h> 

#include <wchar.h> 

int vswprintf(wchar_t *wcsbuffer, size_t n, const wchar_t 
«format, va_list argptr); 


Language Level: ANSI 
Thread Safe: YES. 
Description 


The vswprintf() function formats and stores a series of wide characters and values 
in the buffer wesbuffer. The vswprintf() function works just like the swprintf() 
function, except that argptr points to a list of wide-character arguments whose 
number can vary from call to call. These arguments should be initialized by 
va_start for each call. In contrast, the swprintf() function can have a list of 
arguments, but the number of arguments in that list are fixed when you compile in 
the program. 


The value n specifies the maximum number of wide characters to be written, 
including the ending null character. The vswprintf() function converts each entry 
in the argument list according to the corresponding wide-character format specifier 
in format. The format has the same form and function as the format string for the 
printf() function, with the following exceptions: 


* %oc (without an | prefix) converts an integer argument to wchar_t, as if by calling 
the mbtowc() function. 


¢ %lc converts a wint_t to wchar_t. 


* %s (without an | prefix) converts an array of multibyte characters to an array of 
wchar_t, as if by calling the mbrtowc() function. The array is written up to, but 
not including, the ending null character, unless the precision specifies a shorter 
output. 

* %ls writes an array of wchar_t. The array is written up to, but not including, the 
ending null character, unless the precision specifies a shorter output. 


A null wide character is added to the end of the wide characters written; the null 
wide character is not counted as part of the returned value. If copying takes place 


between objects that overlap, the behavior is undefined. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) are specified on the compilation command. 


Return Value 


The vswprintf() function returns the number of bytes written in the array, not 
counting the ending null wide character. 


Example that uses vswprintf () 
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This example creates a function vout() that takes a variable number of 
wide-character arguments and uses vswprintf() to print them to westr. 


#include <stdio.h> 
#include <stdarg.h> 
#include <wchar.h> 


wchar_t *format3 
wchar_t *format5 


L"%ls %d %1s"3 
d 


void vout(wchar_t *wcs, size_t n, wchar_t «fmt, ...) 
{ 


va_list arg_ptr; 


va_start(arg_ptr, fmt); 
vswprintf(wes, n, fmt, arg ptr); 
va_end(arg_ptr); 

returns 


} 


int main(void) 
{ 
wchar_t westr[100] ; 


vout(wcstr, 100, format3, L"ONE", 2L, L"THREE"); 
printf("%ls\n", westr); 

vout(wcstr, 100, format5, L"ONE", 2L, L"THREE", 4L, L"FIVE"); 
printf("%ls\n", westr); 

return 0; 


[BRK AK KERR KER KKK KKK AKER KAKA KK EAR KKK KIA KEK KIKI KERR 
The output should be similar to: 


ONE 2 THREE 
ONE 2 THREE 4 FIVE 


KR K KKK KKK KK KKK KEK KKK KKK IKEA KKK AK KEIR KEK K KAA KEK AKER AKER | 


} 


Related Information 


vwprintf() — Format Argument Data as Wide Characters and Print 
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Format 


#include <stdarg.h> 
#include <wchar.h> 
int vwprintf(const wchar_t «format, va_list arg); 


Language Level: ANSI 
Thread Safe: YES. 


Description 
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The vwprintf() function is equivalent to the wprintf() function, except that the 
variable argument list is replaced by arg, which the va_start macro (and possibly 
subsequent va_arg calls) will have initialized. The vwprintf() function does not 
invoke the va_end macro. 


Note: This function is available when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) are specified on the compilation command. 


Return Value 


The vwprintf() function returns the number of wide characters transmitted. If an 
output error occurred, thevwprintf() returns a negative value. 


Example that uses vwprintf() 


This example prints the wide character a. The printing is done from the vout () 
function, which takes a variable number of arguments and uses the 
vwprintf() function to print them to stdout. 


#include <wchar.h> 
#include <stdarg.h> 
#include <locale.h> 


void vout (wchar_t *fmt, ...); 
const char ifs_path[] = "tmp/mytest"; 


int main(void) { 

FILE *stream; 

wehar_t format[] = L"%1c"; 
setlocale(LC_ALL, "POSIX"); 
vout (format, L'a'); 
return(0); 


/* A long a is written to stdout, if stdout is written to the screen 
it may get converted back to a single byte 'a'. »*/ 


void vout (wchar_t *fmt, ...) { 


va_list arg_ptr; 
va_start (arg_ptr, fmt); 
vwprintf (fmt, arg_ptr); 
va_end (arg_ptr); 


} 


Related Information 
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wcrtomb() — Convert a Wide Character to a Multibyte Character 


(Restartable) 


Format 


#include <wchar.h> 
size_t wertomb (char *s, wchar_t wc, mbstate_t *ps); 


Language Level: ANSI 

Thread Safe: Yes, except when ps is NULL. 

Description 

This function is the restartable version of the wctomb() function. 

The wertomb() function converts a wide character to a multibyte character. 


If s is a null pointer, the wcrtomb() function determines the number of bytes 
necessary to enter the initial shift state (zero if encodings are not state-dependent 
or if the initial conversion state is described). The resulting state described will be 
the initial conversion stated. 


If s is not a null pointer, the wcrtomb() function determines the number of bytes 
needed to represent the multibyte character that corresponds to the wide character 
given by we (including any shift sequences), and stores the resulting bytes in the 
array whose first element is pointed to by s. At most MB_CUR_MAxX bytes will be 
stored. If we is a null wide character, the resulting state described will be the initial 
conversions state. 


This function differs from its corresponding internal-state multibyte character 
function in that it has an extra parameter, ps of type pointer to mbstate_t that 
points to an object that can completely describe the current conversion state of the 
associated multibyte character sequence. If ps is NULL, an internal static variable 
will be used to keep track of the conversion state. Using the internal static variable 
is not thread safe. 


When the program is compiled with LOCALETYPE(*LOCALE) and 
SYSIFCOPT(*IFSIO), the behavior of wertomb() is affected by the LC_CTYPE 
category of the current locale. Remember that the CCSID of the locale should 
match the CCSID of your job. If the CCSID of the locale is a single-byte CCSID, the 
wide characters are converted to single-byte characters. Any wide character whose 
value is greater than 256 would be invalid when converting to a single-byte 
CCSID. When the CCSID is a multibyte CCSID, the wide characters are converted 
to multibyte characters. 


When the program is compiled with LOCALETYPE(**LOCALEUCS2) and 
SYSIFCOPT(*IFSIO), the wide characters are assumed to be UNICODE characters. 
These UNICODE characters are converted to the CCSID of the locale associated 
with LC_CTYPE. 


Return Value 
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If s is a null pointer, the wcrtomb() function returns the number of bytes needed to 
enter the initial shift state. The value returned will not be greater than that of the 
MB_CUR_MAX macro. 


If s is not a null pointer, the wcrtomb() function returns the number of bytes stored 
in the array object (including any shift sequences) when we is a valid wide 


character; otherwise (when we is not a valid wide character), an encoding error 


occurs, the value of the macro EILSEQ shall be stored in errno and -1 will be 
returned, but the conversion state will be unchanged. 


Examples that use wcrtomb() 


This program is compiled with LOCALETYPE(*LOCALE) and SYSIFCOPT(*IFSIO): 


#include <stdio.h> 
#include <locale.h> 
#include <wchar.h> 
#include <errno.h> 


#define STRLENGTH 10 
#define LOCNAME —— "qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 


{ 


char string[STRLENGTH] ; 

int length, sl = 0; 

wchar_t we = Qx4171; 

wchar_t we2 = Qx00C1; 

wehar_t wce_string[10]; 
mbstate_t ps = Q; 

memset(string, '\0', STRLENGTH); 


we_string[0] = 0x00C1; 
we_string[1] = 0x4171; 
we_string[2] = 0x4172; 
we_string[3] = 0x00C2; 
we_string[4] = 0x0000; 


/* In this first example we will convert a wide character */ 
/* to a single byte character. We first set the locale */ 


/* to a single byte locale. We choose a locale with x/ 
/* CCSID 37. For single byte cases the state will always */ 
/* remain in the initial state 0 x/ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 


length = wertomb(string, wc, &ps); 

/* In this case since wc > 256 hex, lenth is -1 and */ 

/* errno is set to EILSEQ (3492) */ 

printf("errno = %d, length = %d\n\n", errno, length); 

length = wcrtomb(string, wc2, &ps); 

/* In this case wc2 00C1 is converted to C1 */ 

printf("string = %s\n\n", string); 

/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 


/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 
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} 
/* 


length = wcertomb(string, wc_string[0], &ps); 


/* The first character is < 256 hex so is converted to 
/* single byte and the state is still the initial state 0 


printf("length = %d, state = %d\n\n", length, ps); 

sl] += length; 

length = wcrtomb(&string[sl], wc_string[1], &ps); 

/* The next character is > 256 hex so we get a shift out 
/* OxOe followed by the double byte character. State is 
/* changed to double byte state. Length is 3. 
printf("length = %d, state = %d\n\n", length, ps); 

sl] += length; 

length = wcrtomb(&string[sl], wc_string[2], &ps); 

/* The next character is > 256 hex so we get another 

/* double byte character. The state is left in 

/* double byte state. Length is 2. 

printf("length = %d, state = %d\n\n", length, ps); 

sl] += length; 

length = wcrtomb(&string[sl], wc_string[3], &ps); 

/* The next character is < 256 hex so we close off the 
/* double byte characters with a shift in OxOf and then 
/* get a single byte character. Length is 2. 


/* The hex look at string would now be: 
/* C10E417141720FC2 


/* You would need a device capable of displaying multibyte 


/* characters to see this string. 
printf("length = %d, state = %d\n\n", length, ps); 


/* In the last example we will show what happens if NULL 
/* is passed in for the state. 
memset(string, '\@', STRLENGTH); 


length = wertomb(string, wc_string[1], NULL); 


/* The second character is > 256 hex so a shift out 

/* followed by the double character is produced but since 
/* the state is NULL, the double byte character is closed 
/* off with a shift in right away. So string we look 

/* like this: 0E41710F and length is 4 and the state is 
/* left in the initial state. 


printf("length = %d, state = %d\n\n", length, ps); 


The output should look like this: 


errno = 3492, length = -1 


string =A 
length = 1, state = 0 
length = 3, state = 2 
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*/ 


*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


length 


= 2, state = 2 
length = 2, state = 0 
length = 4, state = 0 


*/ 


This program is compiled with LOCALETYPE(*LOCALEUCS2) and 
SYSIFCOPT(*IFSIO): 


#include <stdio.h> 
#include <locale.h> 
#include <wchar.h> 
#include <errno.h> 


#define STRLENGTH 10 
#define LOCNAME —— "qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 


{ 


char string[STRLENGTH] ; 

int length, sl = 0; 

wchar_t = we = Qx4171; 

wchar_t wc2 = Qx0041; 

wchar_t wce_string[10]; 
mbstate_t ps = Q; 

memset(string, '\0', STRLENGTH); 


we_string[0] = 0x0041; 
we_string[1] = OxFF31; 
we_string[2] = OxFF32; 
we_string[3] = 0x0042; 
we_string[4] = 0x0000; 


/* In this first example we will convert a UNICODE character */ 
/* to a single byte character. We first set the locale */ 


/* to a single byte locale. We choose a locale with */ 
/* CCSID 37. For single byte cases the state will always */ 
/* remain in the initial state 0 */ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 


length = wcrtomb(string, wc2, &ps); 


/* In this case wc2 0041 is converted to Cl +*/ 
/* 0041 is UNICODE A, C1 is CCSID 37 A */ 


printf("string = %s\n\n", string); 

/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 ~*/ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = wcertomb(string, wc_string[0], &ps); 


/* The first character UNICODE character is converted to a */ 
/* single byte and the state is still the initial state 0 */ 


printf("length = %d, state = %d\n\n", length, ps); 
sl] += length; 


length = wcertomb(&string[sl], wc_string[1], &ps); 
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/* The next UNICODE character is converted to a shift out */ 
/* 0xOe followed by the double byte character. State is */ 
/* changed to double byte state. Length is 3. */ 
printf("length = %d, state = %d\n\n", length, ps); 

sl] += length; 


length = wcrtomb(&string[sl], wc_string[2], &ps); 


/* The UNICODE character is converted to another */ 
/* double byte character. The state is left in */ 
/* double byte state. Length is 2. x/ 


printf("length = %d, state = %d\n\n", length, ps); 
sl] += length; 
length = wcrtomb(&string[sl], wc_string[3], &ps); 


/* The next UNICODE character converts to single byte so */ 


/* we close off the x/ 
/* double byte characters with a shiftin OxOf and then */ 
/* get a single byte character. Length is 2. x/ 
/* The hex look at string would now be: */ 
/* C10E42D842D90FC2 x/ 
/* You would need a device capable of displaying multibyte */ 
/* characters to see this string. */ 


printf("length = %d, state = %d\n\n", length, ps); 


} 
/* The output should look like this: 


string = A 

length = 1, state = 0 
length = 3, state = 2 
length = 2, state = 2 
length = 2, state = 0 


*/ 


Related Information 


wcscat() — Concatenate Wide-Character Strings 
Format 
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#include <wcstr.h> 
wchar_t *wcscat(wchar_t *stringl, const wchar_t *string2); 


Language Level: XPG4 
Description 


The wescat() function appends a copy of the string pointed to by string2 to the 
end of the string pointed to by string1. 


The wescat() function operates on null-ended wchar_t strings. The string 
arguments to this function should contain a wchar_t null character marking the 
end of the string. Boundary checking is not performed. 


Return Value 
The wcscat() function returns a pointer to the concatenated string1. 
Example that uses wcscat() 


This example creates the wide character string "computer program” using the 
wescat() function. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wehar_t bufferl[SIZE] 
wchar_t * string 
wchar_t * ptr; 


L"computer"; 
L" program"; 


ptr = wcescat( bufferl, string ); 
printf( "bufferl = %ls\n", bufferl ); 


} 


[BEKRKEKEKEREKKR Output should be similar tO: ***kXKKKKKKEKKKKEK 


bufferl = computer program 
KA KK RA KKK AK KKK KKK KK KEK KKK AKER AKER IKEA KKK AKA KKK KEI AKER AKER AK | 


Related Information 
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wcschr() — Search for Wide Character 


402 


Format 


#include <wcstr.h> 
wchar_t *wcschr(const wchar_t *string, wchar_t character) ; 


Language Level: XPG4 
Description 


The weschr() function searches the wide-character string for the occurrence of 
character. The character can be a wchar_t null character (\0); the wchar_t null 
character at the end of string is included in the search. 


The weschr() function operates on null-ended wchar_t strings. The string 
argument to this function should contain a wchar_t null character marking the end 
of the string. 


Return Value 


The weschr() function returns a pointer to the first occurrence of character in string. 
If the character is not found, a NULL pointer is returned. 


Example that uses wcschr() 


man 


This example finds the first occurrence of the character "p" in the wide-character 
string "computer program”. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wehar_t buffer1l[SIZE] = L"computer program"; 
wchar_t * ptr; 
wchar_t ch = L'p'; 


ptr = weschr( bufferl, ch ); 
printf( "The first occurrence of %lc in '%ls' is '%ls'\n", 
ch, bufferl, ptr ); 
} 


[KEKRKRRRKEEEKKE Output should be similar tO: ****X*KKKKKKKKKKKE 


The first occurrence of p in ‘computer program' is 'puter program' 


*/ 


Related Information 
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wcscmp() — Compare Wide-Character Strings 


Format 


#include <wcstr.h> 
int wcscmp(const wchar_t *stringl, const wchar_t *string2); 


Language Level: ANSI 
Description 


The wescmp() function compares two wide-character strings. The wcscmp() function 
operates on null-ended wchar_t strings; string arguments to this function should 
contain a wchar_t null character marking the end of the string. Boundary checking 
is not performed when a string is added to or copied. 


Return Value 


The wescmp() function returns a value indicating the relationship between the two 
strings, as follows: 


Value Meaning 


Less than 0 
string] less than string2 


0 string1 identical to string2 


Greater than 0 
string] greater than string2. 


Example that uses wcscmp() 


This example compares the wide-character string string] to string2 using wcscmp(). 


#include <stdio.h> 
#include <wcstr.h> 


int main(void) 

{ 
int result; 
wehar_t stringl[] 
wehar_t string2[] 


L"abcdef"; 
L"abcdefg"s 


result = wcscmp( stringl, string2 ); 


if ( result == 0 ) 

printf( "\"%ls\" is identical to \"%ls\"\n", stringl, string2); 
else if ( result < 0 ) 

printf( "\"%ls\" is less than \"%ls\"\n", stringl, string2 ); 
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else 
printf( "\"%ls\" is greater than \"%ls\"\n", stringl, string2); 


[KEKRKRERKKERKKE Output should be similar tO: **XkXKKKKKKEKKKKKK 


"abcdef" is less than "abcdefg" 
x/ 


Related Information 


wcscoll() —Language Collation String Comparison 
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Format 
#include <wchar.h> 


int wcescoll (const wchar_t *wcsl, const wchar_t *wcs2); 

Language Level: XPG4 

Description 

The wescol1() function compares the wide-character strings pointed to by wes1 
and wes2, both interpreted as appropriate to the LC_COLLATE category of the 


current locale. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


The behavior of this wide-character function is affected by the LC_COLLATE 
category of the current locale. 


Although this function is accessible when compiled with 
LOCALETYPE(*LOCALEUCS2), UNICODE is not supported by this function. 


Return Value 


The wescol1() function returns an integer value indicationg the relationship 
between the strings, as follows: 


Value Meaning 
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Less than 0 
wesl less than wes2 


0 wes1 equivalent to wes2 


Greater than 0 
wes1 greater than wes2 


If wes1 or wes2 contain characters outside the domain of the collating sequence, the 
wcescol1() function sets errno to EINVAL. If an error occurs, the wcscol1() function 
sets errno to an nonzero value. There is no error return value. 


If wescoll() is unsuccessful, errno is changed. The value of errno may be set to 
EINVAL (the wes1 or wes2 arguments contain characters which are not available in 
the current locale). 


Example that uses wcscol] () 
This example uses the default locale. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 

{ 
int result; 
wchar_t *wcsl 
wchar_t *wcs2 


L"first_wide_ string"; 
L"second_wide_ string"; 


result = wcscoll(wcsl, wcs2); 


if ( result == 0) 

printf("\"%S\" is identical to \"%S\"\n", wesl, wcs2); 
else if ( result < 0) 

printf("\"%S\" is less than \"%S\"\n", wesl, wcs2); 
else 

printf("\"%S\" is greater than \"%S\"\n", wesl, wcs2); 


Related Information 


wcescpy() — Copy Wide-Character Strings 
Format 
#include <wcstr.h> 
wchar_t *wcscpy(wchar_t *stringl, const wchar_t *string2); 
Language Level: XPG4 


Description 


The wescpy() function copies the contents of string2 (including the ending wchar_t 
null character) into string1. 
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The wescpy() function operates on null-ended wchar_t strings; string arguments to 
this function should contain a wchar_t null character marking the end of the 
string. Only string2 needs to contain a null character. Boundary checking is not 
performed. 


Return Value 

The wescpy() function returns a pointer to string1. 
Example that uses wcscpy() 

This example copies the contents of source to destination. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wchar_t source[ SIZE ] = L"This is the source string"; 
wchar_t destination[ SIZE ] = L"And this is the destination string"; 
wchar_t * return_string; 


printf( "destination is originally = \"%ls\"\n", destination ); 
return_string = wcscpy( destination, source ); 
printf( "After wcscpy, destination becomes \"%1ls\"\n", destination ); 


} 

[KEKRKEKRKEREKER Output should be similar tO: ***kXKKKKKKKKKKKEK 
destination is originally = "And this is the destination string" 
After wcscpy, destination becomes "This is the source string" 


*/ 


Related Information 


wcscspn() — Find Offset of First Wide-Character Match 


Format 
#include <wcstr.h> 
size_t wcescspn(const wchar_t *stringl, const wchar_t *string2); 


Language Level: XPG4 


Description 
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The wescspn() function determines the number of wchar_t characters in the initial 
segment of the string pointed to by string1 that do not appear in the string pointed 
to by string2. 


The wescspn() function operates on null-ended wchar_t strings; string arguments 
to this function should contain a wchar_t null character marking the end of the 
string. 


Return Value 
The wescspn() function returns the number of wchar_t characters in the segment. 
Example that uses wcscspn() 


This example uses wcscspn() to find the first occurrence of any of the characters a, 
x, | or e in string. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wehar_t string[SIZE] = L"This is the source string"; 
wchar_t * substring = L"axle"; 


printf( "The first %i characters in the string \"%ls\" are not in the " 
"string \"%1ls\" \n", wescspn( string, substring), 
string, substring ); 


} 


[EKRKEKREKEREKKR Output should be similar tO: ***kXKKKKKKKKKKKEK 


The first 10 characters in the string "This is the source string" are not 
in the string "axle" 


*/ 


Related Information 


wcsftime() — Convert to Formatted Date and Time 


Format 


#include <wchar.h> 
size_t wcsftime(wchar_t *wdest, size_t maxsize, 
const wchar_t *format, const struct tm *timeptr); 
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Language Level: ANSI 
Description 


The wesftime() function converts the time and date specification in the timeptr 
structure into a wide-character string. It then stores the null-ended string in the 
array pointed to by wdest according to the format string pointed to by format. The 
maxsize value specifies the maximum number of wide characters that can be copied 
into the array. This function is equivalent to strftime(), except that it uses wide 
characters. 


The wesftime() function works just like the strftime() function, except that it uses 
wide characters. The format string is a wide-character character string that 
contains: 


* Conversion-specification characters. 
* Ordinary wide characters, which are copied into the array unchanged. 


Note: When wesftime() is compiled with LOCALETYPE(*7LOCALEUCS2) wdest 
and format, both must be UNICODE-encoded strings, as opposed to wide 
EBCDIC. This function is availabe only when LOCALETYPE is (*LOCALE) 
or (“LOCALEUCS2). 


This function uses the time structure pointed to by timeptr, and if the specifier is 
locale sensitive, then it will also use the LC_TIME category of the current locale to 
determine the appropriate replacement value of each valid specifier. The time 
structure pointed to by timeptr is usually obtained by calling the gmtime() or 
localtime() function. 


Return Value 


If the total number of wide characters in the resulting string, including the ending 
null wide character, does not exceed maxsize, wcsftime() returns the number of 
wide characters placed into wdest, not including the ending null wide character. 
Otherwise, the wcsftime() function returns 0 and the contents of the array are 
indeterminate. 


Example that uses wcsftime() 


This example obtains the date and time using local time(), formats the information 
with the wcsftime(), and prints the date and time. 


#include <stdio.h> 
#include <time.h> 
#include <wchar.h> 


int main(void) 

{ 
struct tm *timeptr; 
wechar_t  dest[100]; 
time_t temp; 
size_t rc; 


temp = time(NULL) ; 
timeptr = localtime(&temp) ; 
rc = wesftime(dest, sizeof(dest), L" Today is %A," 
L" %b %d.\n Time: %1:%M %p", timeptr); 
printf("%d characters placed in string to make:\n\n%ls\n", rc, dest); 
return 0; 
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[RRR KKK IKKE AK KEI KK AK KKK KKK KKK IK KKK AKER KKK A KKK KK KAKA KIRKE RAKE 
The output should be similar to: 


43 characters placed in string to make: 


Today is Thursday, Nov 10. 
Time: 04:56 PM 


KKK KKK KK KK A KK EA K KEIR KKK KKK KEIRA KERRI KEK IKK EA KEKE KARE EKER | 


} 


Related Information 


wcslen() — Calculate Length of Wide-Character String 


Format 


#include <wcstr.h> 
size_t wcslen(const wchar_t *string); 


Language Level: XPG4 
Description 


The weslen() function computes the number of wide characters in the string 
pointed to by string. 


Note: This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


The wcslen() function returns the number of wide characters in string, excluding 
the ending wchar_t null character. 


Example that uses wcslen() 
This example computes the length of the wide-character string string. 


#include <stdio.h> 
#include <wcstr.h> 


int main(void) 
{ 


wchar_t * string = L"abcdef"; 


printf( "Length of \"%ls\" is %i\n", string, wcslen( string )); 


} 


[KEKEKERKEKKRKEKKR Output should be similar tO: **xKXKKKKKKEKKKKKKK 


Length of "abcdef" is 6 
x/ 


Related Information 
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wcsncat() — Concatenate Wide-Character Strings 
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Format 

#include <wcstr.h> 

wchar_t *wcsncat(wchar_t *stringl, const wchar_t *string2, size_t count); 
Language Level: XPG4 


Description 


The wesncat() function appends up to count wide characters from string2 to the 
end of string1, and appends a wchar_t null character to the result. 


The wesncat() function operates on null-ending wide-character strings; string 
arguments to this function should contain a wchar_t null character marking the 
end of the string. 

Return Value 

The wesncat() function returns string1. 

Example that uses wcsncat() 

This example demonstrates the difference between the wcescat() and 
wesncat()functions. The wescat() function appends the entire second string to the 


first; the wcsncat() function appends only the specified number of characters in the 
second string to the first. 
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#include <stdio.h> 
#include <wcstr.h> 
#include <string.h> 


#define SIZE 40 


int main(void) 

{ 
wehar_t bufferl[SIZE] = L"computer"; 
wchar_t * ptr; 


/* Call wescat with bufferl and " program" «/ 


ptr = wcescat( bufferl, L" program" ); 
printf( "wescat : bufferl = \"%ls\"\n", bufferl ); 


/* Reset bufferl to contain just the string "computer" again */ 


memset( bufferl, L'\O', sizeof( bufferl )); 
ptr = wcescpy( bufferl, L"computer" ); 


/* Call wesncat with bufferl and " program" */ 

ptr = wcesncat( bufferl, L" program", 3 ); 

printf( "wcsncat: bufferl = \"%ls\"\n", bufferl ); 
} 


[REKRKEKEKERERER Output should be similar tO: ******KKKKKKKKKKKK 


wescat : bufferl 
wesncat: bufferl 
x/ 


"computer program" 
"computer pr" 


Related Information 


wcsncmp() — Compare Wide-Character Strings 
Format 
#include <wcstr.h> 
int wcsncmp(const wchar_t *stringl, const wchar_t *string2, size_t count); 
Language Level: XPG4 
Description 
The wesncmp() function compares up to count wide characters in string] to string2. 
The wesncmp() function operates on null-ended wide-character strings; string 
arguments to this function should contain a wchar_t null character marking the 


end of the string. 


Note: This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 
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The wesncmp() function returns a value indicating the relationship between the two 
strings, as follows: 


Value Meaning 


Less than 0 
string] less than string2 


0 string identical to string2 


Greater than 0 
string] greater than string2. 


Example that uses wcsncmp() 


This example demonstrates the difference between the wcscmp() function, which 
compares the entire strings, and the wcsncmp() function, which compares only a 
specified number of wide characters in the strings. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 10 


int main(void) 
{ 
int result; 
int index = 3; 
wehar_t buffer1[SIZE] = L"abcdefg"; 
wehar_t buffer2[SIZE] = L"abcfg"; 
void print_result( int, wchar_t *, wchar_t * ); 


result = wcscmp( bufferl, buffer2 ); 
printf( "Comparison of each character\n" ); 
printf( "  wescmp: " ); 

print_result( result, bufferl, buffer2 ); 


result = wcsncmp( bufferl, buffer2, index); 
printf( "\nComparison of only the first %i characters\n", index ); 
printf( "  wcsncmp: " ); 
print_result( result, bufferl, buffer2 ); 
} 


void print_result( int res, wchar_t * p_bufferl, wchar_t * p_buffer2 ) 
{ 
if ( res == 0 ) 
printf( "\"%ls\" is identical to \"%ls\"\n", p_bufferl, p_buffer2); 
else if ( res < 0 ) 
printf( "\"%ls\" is less than \"%1s\"\n", p_bufferl, p_buffer2 ); 
else 
printf( "\"%ls\" is greater than \"%ls\"\n", p_bufferl, p_buffer2 ); 
} 


[#EKRKRKRKEEEKKE Output should be similar tO: ******KKKKKKKKKKKE 


Comparison of each character 
wcescmp: "abcdefg" is less than "abcfg" 


Comparison of only the first 3 characters 
wesncmp: "“abcdefg" is identical to "abcfg" 
x/ 


Related Information 
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wesncpy() — Copy Wide-Character Strings 


Format 

#include <wcstr.h> 

wchar_t *wcsncpy(wchar_t *stringl, const wchar_t *string2, size_t count); 
Language Level: XPG4 

Description 

The wesncpy() function copies up to count wide characters from string2 to string1. 
If string2 is shorter than count characters, string] is padded out to count characters 
with wchar_t null characters. 

The wesncpy() function operates on null-ended wide-character strings; string 
arguments to this function should contain a wchar_t null character marking the 
end of the string. Only string2 needs to contain a null character. 

Return Value 


The wesncpy() returns a pointer to string]. 


Related Information 


__wcsicmp — Compare Wide Character Strings without Case 


Sensitivity 


Format 


#include <wchar.h> 

int __wcsicmp(const wchar_t *stringl, const wchar_t *string2); 

Language Level: Extension 

Thread Safe: YES. 

Description 

The __wcsicmp() function compares string1 and string2 without sensitivity to case. 


All alphabetic wide characters in string] and string2 are converted to lowercase 
before comparison. The function operates on null terminated wide character 
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strings. The string arguments to the function are expected to contain a wchar_t null 
character (L'\0') marking the end of the string. 


Return Value 


The__wcsicmp() function returns a value indicating the relationship between the 
two strings as follows: 


Table 10. Return values of _wcsicmp() 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string] greater than string2 


Example that uses __wcsicmp() 


This example uses __wcsicmp() to compare two wide character strings. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 

{ 
wchar_t *strl = L"STRING"; 
wehar_t *str2 = L"string"; 
int result; 


result = __wcesicmp(strl, str2); 
if (result == 0) 
printf("Strings compared equal.\n"); 
else if (result < Q) 
printf("\"%ls\" is less than \"%1s\".\n", strl, str2); 
else 
printf("\"%ls\" is greater than \"%ls\".\n", strl, str2); 


return 0; 


} 
/xxxxxxxx The output should be similar to: ****xxxxxee kee 
Strings compared equal. 


KKK KKK KKK KEKE AK KEK K KKK KEKE KEEKEREK | 


Related Information 
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__wcsnicmp — Compare Wide Character Strings without Case 


Sensitivity 


Format 
#include <wchar.h>; 


int __wcsnicmp(const wchar_t *stringl, const wchar_t *string2, size_t count); 
Language Level: Extension 

Thread Safe: YES. 

Description 

The __wcsnicmp() function compares up to count characters of string1 and string2 
without sensitivity to case. All alphabetic wide characters in string1 and string2 are 
converted to lowercase before comparison. 

The __wcsnicmp() function operates on null terminated wide character strings. The 
string arguments to the function are expected to contain a wchar_t null character 
(L'\O') marking the end of the string. 


Return Value 


The__wcsnicmp() function returns a value indicating the relationship between the 
two strings, as follows: 


Table 11. Return values of _wcsicmp() 


Value Meaning 

Less than 0 string] less than string2 

0 string] equivalent to string2 
Greater than 0 string1 greater than string2 


Example that uses __wcsnicmp() 


This example uses __wcsnicmp() to compare two wide character strings. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 
{ 
wchar_t *strl 
wchar_t *str2 
int result; 


L"STRING ONE"; 
L"string TWO"; 


result = __wesnicmp(str1, str2, 6); 


if (result == 0) 

printf("Strings compared equal.\n"); 
else if (result < 0) 

printf("\"%ls\" is less than \"%1s\".\n", strl, str2); 
else 

printf("\"%1ls\" is greater than \"%1s\".\n", strl, str2); 


return 0; 


} 


/xxxxxxxe The output should be similar to: ****xxxxxxK Kee 
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Strings compared equal. 


KKK KKK KKK KK EAR KEK KKK AKER KEKE KEEKEREK | 


Related Information 


wcspbrk() — Locate Wide Characters in String 


416 


Format 

#include <wcstr.h> 

wchar_t *wcspbrk(const wchar_t *stringl, const wchar_t *string2); 
Language Level: XPG4 


Description 


The wespbrk() function locates the first occurrence in the string pointed to by 
string] of any wide character from the string pointed to by string2. 


Return Value 


The wespbrk() function returns a pointer to the character. If string] and string2 
have no wide characters in common, the wcspbrk() function returns NULL. 


Example that uses wcspbrk() 


nw 


This example uses wespbrk() to find the first occurrence of either "a" or "b" in the 
array string. 
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#include <stdio.h> 
#include <wcstr.h> 


int main(void) 

{ 
wchar_t * result; 
wchar_t * string = L"The Blue Danube"; 
wchar_t *chars = L"ab"; 


result = wcspbrk( string, chars); 
printf("The first occurrence of any of the characters \"%ls\" in " 
"\"%1s\" is \"%1s\"\n", chars, string, result); 
} 
[KEKRKEKEKERERKR Output should be Similar tO: ***kXKKKKKKKKKKKEKK 
The first occurrence of any of the characters "ab" in "The Blue Danube" 


+ u u 
is "anube 
KKK KKK KKK KKK A KKK KK KKK K KKK KEK KKK IK KKK KKK A KKK AK KIA IKEA KK ERK KER KEKE | 


Related Information 


wesrchr() — Locate Last Occurrence of Wide Character in String 


Format 

#include <wcstr.h> 

wchar_t *wcsrchr(const wchar_t *string, wchar_t character) ; 

Description 

The wesrchr() function locates the last occurrence of character in the string pointed 
to by string. The ending wchar_t null character is considered to be part of the 
string. 


Return Value 


The wesrchr() function returns a pointer to the character, or a NULL pointer if 
character does not occur in the string. 


Example that uses wcsrchr() 


This example compares the use of weschr() and wesrchr(). It searches the string 
for the first and last occurrence of p in the wide character string. 
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#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wchar_t buf[SIZE] = L"computer program"; 
wchar_t * ptr; 
int ch = 'p'; 


/* This illustrates weschr */ 
ptr = weschr( buf, ch ); 
printf( "The first occurrence of %c in '%ls' is '%ls'\n", ch, buf, ptr ); 


/* This illustrates wscrchr */ 
ptr = wesrchr( buf, ch ); 
printf( "The last occurrence of %c in '%ls' is '%ls'\n", ch, buf, ptr ); 


} 


[KEKRKRKRKEREKRKE Output should be similar tO: ***kXKKKKKKEKKKKEK 
The first occurrence of p in ‘computer program’ is 'puter program' 
The last occurrence of p in ‘computer program' is 'program' 


*/ 


Related Information 


wcsrtombs() — Convert Wide Character String to Multibyte String 


(Restartable) 


Format 


#include <wchar.h> 
size_t wcsrtombs (char *dst, const wchar_t **src, size_t len, 
mbstate_t *ps); 


Language Level: ANSI 
Thread Safe: Yes, if the fourth parameter, ps, is not NULL. 
Description 


This function is the restartable version of wcstombs(). 
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The wesrtombs() function converts a sequence of wide characters from the array 
indirectly pointed to by src into a sequence of corresponding multibyte characters 
that begins in the shift state described by ps, which, if dst is not a null pointer, are 
then stored into the array pointed to by dst. Conversion continues up to and 
including the ending null wide character, but the ending null character (byte) will 
not be stored. Conversion will stop earlier in two cases: when a code is reached 
that does not correspond to a valid multibyte character, or (if dst is not a null 
pointer) when the next multibyte element would exceed the limit of Jen total bytes 
to be stored into the array pointed to by dst. Each conversion takes place as if by a 
call to wcrtomb(). 


If dst is not a null pointer, the object pointed to by src will be assigned either a null 
pointer (if conversion stopped due to reaching a ending null character) or the 
address of the code just past the last wide character converted. If conversion 
stopped due to reaching a ending null wide character, the resulting state described 
will be the initial conversion state. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


If the program is compiled with LOCALETYPE(*LOCALEUCS2), it will 
behave as if it was compiled with LOCALETYPE(*LOCALE), since this 
function does not support UNICODE yet. 


Return Value 

If the first code is not a valid wide character, an encoding error will occur. 
wcesrtombs() stores the value of the macro EILSEQ in errno and returns (size_t) -1, 
but the conversion state will be unchanged. Otherwise it returns the number of 
bytes in the resulting multibyte character sequence, which is the same as the 


number of array elements changed when dst is not a null pointer. 


Example that uses wcsrtombs () 


Chapter 2. Library Functions 419 


#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


#define SIZE 20 


int main(void) 

{ 
char dest [SIZE]; 
wchar_t *wcs = L"string"; 
wcehar_t *ptr; 
size_t count = SIZE; 
size_t length; 
mbstate_t ps = Q; 


ptr = (wchar_t *) wes; 

length = wcsrtombs(dest, ptr, count, &ps); 
printf("%d characters were converted.\n", length); 
printf("The converted string is \"%s\"\n\n", dest); 


/* Reset the destination buffer */ 
memset(dest, '\Q', sizeof(dest)); 


/* Now convert only 3 characters */ 

ptr = (wchar_t *) wes; 

length = wcsrtombs(dest, ptr, 3, &ps); 

printf("%d characters were converted.\n", length); 
printf("The converted string is \"%s\"\n\n", dest); 


} 


[KEKRKKEREKEREKERK Output should be Similar tO: *k*KXKKKKKKKKKKKEKKKKE 


6 characters were converted. 
The converted string is "string" 


3 characters were converted. 
The converted string is "str" 
x/ 


Related Information 


wcsspn() — Find Offset of First Non-matching Wide Character 


420 


Format 


#include <wcstr.h> 
size_t wesspn(const wchar_t *stringl, const wchar_t *string2); 


Description 
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The wesspn() function computes the number of wide characters in the initial 
segment of the string pointed to by string1, which consists entirely of wide 
characters from the string pointed to by string2. 


Return Value 
The wesspn() function returns the number of wide characters in the segment. 
Example that uses wcsspn() 


This example finds the first occurrence in the array string of a wide character that 
is not an a, b, or c. Because the string in this example is cabbage, the wcsspn() 
function returns 5, the index of the segment of cabbage before a character that is 
not an a,b, orc. 


#include <stdio.h> 
#include <wcstr.h> 


int main(void) 

{ 
wchar_t * string 
wchar_t * source 
int index; 


L"cabbage"; 
L"abc"; 


index = wesspn( string, L"abc" ); 
printf( "The first %d characters of \"%1s\" are found in \"%1s\"\n", 
index, string, source ); 
} 


[REKRKEKEKEREKKR Output should be similar tO: ***KXKKKKKKEKKKKKK 


The first 5 characters of "cabbage" are found in "abc" 
*/ 


Related Information 


wcsstr() — Locate Wide-Character Substring 


Format 


Chapter 2. Library Functions 421 


#include <wchar.h> 
wehar_t *wcsstr(const wchar_t *wcsl, const wchar_t *wcs2); 


Language Level: ANSI 

Description 

The wcsstr() function locates the first occurrence of wes2 in wes1. 

Return Value 

The wesstr() function returns a pointer to the beginning of the first occurrence of 
wes2 in wes1. If wes2 does not appear in wes1, the wesstr() function returns NULL. 
If wes2 points to a wide-character string with zero length, it returns wes1. 


Example that uses wcsstr() 


This example uses the wesstr() function to find the first occurrence of "hay" in the 
wide-character string "needle in a haystack". 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 


wchar_t *wcsl 
wchar_t *wcs2 


L"needle in a haystack"; 
L"hay"s 


printf("result: \"%ls\"\n", wcsstr(wcsl, wcs2)); 
return 0; 


[BERR K KERR KERRI KERIKERI AKA K KEK KEIR EKER KK 
The output should be similar to: 


result: "haystack" 


KKK KK KKK KK KKK KKK KKK KKK KKK KKK KKK ARK ERA KKK | 


} 


Related Information 


wcstod() — Convert Wide-Character String to Double 


422 


Format 
#include <wchar.h> 


double wcstod(const wchar_t *nptr, wchar_t **endptr) ; 

Language Level: XPG4 

Description 

The westod() function converts the initial portion of the wide-character string 


pointed to by nptr to a double value. The nptr parameter points to a sequence of 
characters that can be interpreted as a numerical value of type double. The 
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westod() function stops reading the string at the first character that it cannot 
recognize as part of a number. This character can be the wchar_t null character at 
the end of the string. 


The behavior of the wcestod() function is affected by the LC_CTYPE category of the 
current locale. This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


If the program is compiled LOCALETYPE(**LOCALEUCS2), then the wide 
characters being converted are assumed to be UNICODE characters. 


Return Value 


The wcstod() function returns the converted double value. If no conversion could 
be performed, the westod() function returns 0. If the correct value is outside the 
range of representable values, the wcstod() function returns +HUGE_VAL or 
-HUGE_VAL (according to the sign of the value), and sets errno to ERANGE. If the 
correct value would cause underflow, the wcstod() function returns 0 and sets 
errno to ERANGE. If the string nptr points to is empty or does not have the 
expected form, no conversion is performed, and the value of nptr is stored in the 
object pointed to by endptr, provided that endptr is not a null pointer. 


The value of errno may be set to ERANGE, range error. 
Example that uses wcstod() 


This example uses the wcstod() function to convert the string wcs to a 
floating-point value. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 

{ 
wehar_t *wcs = L"3.1415926This stopped it"; 
wchar_t *stopwcs; 


printf("wes = \"%1s\"\n", wes); 

printf("  wcstod = %f\n", wcstod(wcs, &stopwcs)); 
printf(" Stop scanning at \"%1ls\"\n", stopwcs); 
return 0; 


[RK KK RAK KEIR KEK KKK KK KAKI KKK AKER A KK AKER KK 
The output should be similar to: 


wes = "3.1415926This stopped it" 
westod = 3.141593 
Stop scanning at "This stopped it" 


KKK KKK KKK KER AKK EA KK IK KEK KKK KKK EK KKK AKER AK EERK EK | 


} 


Related Information 
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wcstol() — wcstoll() — Convert Wide Character String to Long and 
Long Long Integer 


424 


Format (wcstol ()) 


#include <wchar.h> 
long int wcestol(const wchar_t *nptr, wchar_t **endptr, int base); 


Format (wcstol1 ()) 


#include <wchar.h> 
long long int wcstoll(const wchar_t *nptr, wchar_t **endptr, int base); 


Language Level: ANSI 
Description 


The westol() function converts the initial portion of the wide-character string 
pointed to by nptr to a long integer value. The nptr parameter points to a sequence 
of wide characters that can be interpreted as a numerical value of type long int. 
The wcstol ()function stops reading the string at the first wide character that it 
cannot recognize as part of a number. This character can be the wchar_t null 
character at the end of the string. The ending character can also be the first 
numeric character greater than or equal to the base. 


The behavior of the wcstol() function is affected by the LC_CTYPE category of the 
current locale. This function is available only when LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


If a program is compiled with LOCALETYPE(*LOCALEUCS2), the wide characters 
being converted are assumed to be UNICODE characters. 


The westol1() subroutine converts a wide-character string to a long long integer. 
The wide-character string is parsed to skip the initial space characters (as 
determined by the iswspace subroutine). Any non-space character signifies the start 
of a subject string that may form a long long int in the radix specified by the base 
parameter. The subject sequence is defined to be the longest initial substring that is 
a long long int of the expected form. 


If the value of the endptr parameter is not null, then a pointer to the character that 
ended the scan is stored in endptr. If a long long integer cannot be formed, the 
value of the endptrparameter is set to that of the nptr parameter. 


If the base parameter is a value between 2 and 36, the subject sequence’s expected 
form is a sequence of letters and digits representing a long long integer whose 
radix is specified by the base parameter. This sequence optionally is preceded by a 
positive (+) or negative (-) sign. Letters from a (or A) to z (or Z) inclusive are 
ascribed the values 10 to 35; only letters whose ascribed values are less than that of 
the base parameter are permitted. If the base parameter has a value of 16, the 
characters Ox or OX optionally precede the sequence of letters and digits, following 
the positive (+) or negative (-) sign, if present. 


If the value of the base parameter is 0, the string determines the base. Therefore, 
after an optional leading sign, a leading 0 indicates octal conversion, and a leading 
Ox or OX indicates hexadecimal conversion. 
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Return Value 


The wcstol() function returns the converted long integer value. If no conversion 
could be performed, the wcstol() function returns 0. If the correct value is outside 
the range of representable values, the wcstol () function returns LONG_MAX or 
LONG_MIN (according to the sign of the value), and sets errno to ERANGE. If the 
string nptr points to is empty or does not have the expected form, no conversion is 
performed, and the value of nptr is stored in the object pointed to by endptr, 
provided that endptr is not a null pointer. 


Upon successful completion, the wcsto11() subroutine returns the converted value. 
If no conversion could be performed, 0 is returned, and the errno global variable is 
set to indicate the error. If the correct value is outside the range of representable 
values, the wcstol1() subroutine returns a value of LONG_LONG_ MAX or 
LONG_LONG_MIN. 


The value of errno may be set to ERANGE (range error), or EINVAL (invalid 
argument). 


Example that uses wcstol () 


This example uses the wcstol() function to convert the wide-character string wes 
to a long integer value. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 
{ 
wehar_t «wcs = L"10110134932"; 
wchar_t *stopwcs; 
long 1; 
int base; 


printf("wes = \"%1s\"\n", wes); 
for (base=2; base<=8; base*=2) { 
1 = westol(wcs, &stopwcs, base); 
printf("  westol = %1d\n" 
"Stopped scan at \"%ls\"\n\n", 1, stopwcs); 
} 


return 0; 


[KEK KKK KKK KEIR KEIR KEK K KKK KKK IK KK EAR AAR EAR KKK KEK KK 
The output should be similar to: 


wes = "10110134932" 
westol = 45 
Stopped scan at "34932" 


westol = 4423 
Stopped scan at "4932" 


westol = 2134108 
Stopped scan at "932" 


KKK KKK KKK KKK AK KEI KK AK KEK KKK KKK KAKA KK AKKEAK REAR | 


} 


Related Information 
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wcstombs() — 


Convert Wide-Character String to Multibyte String 


Format 


#include <stdlib.h> 
size_t wcstombs(char *dest, const wchar_t *string, size_t count); 


Language Level: ANSI 
Thread Safe: YES. 
Description 


The westombs() function converts the wide-character string pointed to by string 
into the multibyte array pointed to by dest. The converted string begins in the 
initial shift state. The conversion stops after count bytes in dest are filled up or a 
wchar_t null character is encountered. 


Only complete multibyte characters are stored in dest. If the lack of space in dest 
would cause a partial multibyte character to be stored, wcstombs() stores fewer 
than n bytes and discards the invalid character. 


The behavior of this function is affected by the LC_CTYPE category of the current 
locale. 


When the program is compiled with LOCALETYPE(*LOCALE) and 
SYSIFCOPT(*IFSIO), the behavior of wcestombs() is affected by the LC_CTYPE 
category of the current locale. Remember that the CCSID of the locale should 
match the CCSID of your job. If the CCSID of the locale is a single-byte CCSID, the 
wide characters are converted to single-byte characters. Any wide character whose 
value is greater than 256 would be invalid when converting to single-byte CCSID. 
When the CCSID is multibyte CCSID, the wide characters are converted to 
multibyte characters. 


When the program is compiled with LOCALETYPE(*LOCALEUCS2) and 
SYSIFCOPT(*IFSIO), the wide characters are assumed to be UNICODE characters, 
and these UNICODE characters are converted to the CCSID of the locale that is 
associated with LC_TYPE. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 
The wcstombs() function returns the length in bytes of the multibyte character 


string, not including a ending null character. The value (size_t)-1 is returned if an 
invalid multibyte character is encountered. 
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The value of errno may be set to EILSER (conversion stopped due to input 
character), or ECONVERT (conversion error). 


Examples that use wcstombs () 


This program is compiled with LOCALETYPE(*LOCALE) and SYSIFCOPT(*IFSIO): 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
#include <wchar.h> 


#define STRLENGTH 10 
#define LOCNAME —— "qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN "qsys.1ib/EN_US.locale" 


int main(void) 


{ 


} 
/* 


char string[STRLENGTH] ; 

int length, sl = 0; 

wehar_t  we2[] = L"ABC"; 
wehar_t wce_string[10]; 
mbstate_t ps = Q; 

memset(string, '\0', STRLENGTH); 


we_string[0] = 0x00C1; 
we_string[1] = 0x4171; 
we_string[2] = 0x4172; 
we_string[3] = 0x00C2; 
we_string[4] = 0x0000; 


/* In this first example we will convert a wide character string */ 
/* to a single byte character string. We first set the locale */ 
/* to a single byte locale. We choose a locale with x/ 
/* CCSID 37. x/ 


if (setlocale(LC_ALL, LOCNAME_EN) == NULL) 
printf("setlocale failed.\n"); 


length = wcstombs(string, wc2, 10); 


/* In this case wide characters ABC are converted to */ 
/* single byte characters ABC, length is 3. */ 


printf("string = %s, length = %d\n\n", string, length); 

/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = wcestombs(string, wc_string, 10); 


/* The hex look at string would now be: x/ 
/* C10E417141720FC2 length will be 8 x/ 
/* You would need a device capable of displaying multibyte */ 
/* characters to see this string. */ 


printf("length = %d\n\n", length); 


The output should look like this: 


string = ABC, length = 3 
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length = 8 
x/ 


This program is compiled with LOCALETYPE(*LOCALEUCS2) and 
SYSIFCOPT(*IFSIO): 


#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
#include <wchar.h> 


#define STRLENGTH 10 
#define LOCNAME — "qsys.1ib/JA_JP. locale" 
#define LOCNAME_EN '"qsys.1ib/EN_US.locale" 


int main(void) 
{ 
char string[STRLENGTH] ; 
int length, sl = 0; 
wehar_t  we2[] = L"ABC"; 
wchar_t wc_string[10]; 
mbstate_t ps = 0; 
memset(string, '\@', STRLENGTH); 
we_string[0] = 0x0041; /* UNICODE A */ 
we_string[1] = OxFF41; 
we_string[2] = OxFF42; 
we_string[3] = 0x0042; /* UNICODE B- */ 
we_string[4] = 0x0000; 
/* In this first example we will convert a wide character string */ 
/* to a single byte character string. We first set the locale */ 
/* to a single byte locale. We choose a locale with x/ 
/* CCSID 37. x/ 


nou nt wows 


if (setlocale(LC_ALL, LOCNAME EN) == NULL) 
printf("setlocale failed.\n"); 


length = wcstombs(string, wc2, 10); 


/* In this case wide characters ABC are converted to */ 
/* single byte characters ABC, length is 3. */ 


printf("string = %s, length = %d\n\n", string, length); 

/* Now lets try a multibyte example. We first must set the «/ 
/* locale to a multibyte locale. We choose a locale with */ 
/* CCSID 5026 */ 


if (setlocale(LC_ALL, LOCNAME) == NULL) 
printf("setlocale failed.\n"); 


length = wcestombs(string, wc_string, 10); 

/* The hex look at string would now be: */ 
/* C10E428142820FC2 Jength will be 8 x/ 
/* You would need a device capable of displaying multibyte */ 
/* characters to see this string. */ 


printf("length = %d\n\n", length); 


} 
/* The output should look like this: 


string = ABC, length = 3 
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length = 8 


*/ 


Related Information 


wcstok() — Tokenize Wide-Character String 


Format 


#include <wchar.h> 
wchar_t *wcstok(wchar_t *wcsl, const wchar_t *wcs2, wchar_t **ptr); 


Language Level: ANSI 
Description 


The wcstok() function reads wes1 as a series of zero or more tokens and wes2 as 
the set of wide characters serving as delimiters for the tokens in wes1. A sequence 
of calls to the westok() function locates the tokens inside wces1. The tokens can be 
separated by one or more of the delimiters from wes2. The third argument points 
to a wide-character pointer that you provide where the wcstok() function stores 
information necessary for it to continue scanning the same string. 


When the westok() function is first called for the wide-character string wes1, it 
searches for the first token in wes1, skipping over leading delimiters. The wcstok() 
function returns a pointer to the first token. To read the next token from wes1, call 
the wcstok() function with NULL as the first parameter (wces1). This NULL 
parameter causes the wcstok() function to search for the next token in the previous 
token string. Each delimiter is replaced by a null character to end the token. 


The wcestok() function always stores enough information in the pointer ptr so that 
subsequent calls, with NULL as the first parameter and the unmodified pointer 
value as the third, will start searching right after the previously returned token. 
You can change the set of delimiters (wcs2) from call to call. 


Return Value 

The westok() function returns a pointer to the first wide character of the token, or 
a null pointer if there is no token. In later calls with the same token string, the 
westok() function returns a pointer to the next token in the string. When there are 
no more tokens, the wcstok() function returns NULL. 


Example that uses wcstok() 


This example uses the wcstok() function to locate the tokens in the wide-character 
string str1. 
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#include <stdio.h> 
#include <wchar.h> 


int main(void) 

{ 
static wchar_t stri[] = L"?a??b,,,#c"s 
static wchar_t str2[] = L"\t \t"s 
wehar_t *t, *ptrl, *ptr2; 


t = westok(strl, L"?", &ptr1);  /* t points to the token L"a" «/ 
printf("t = '%1s'\n", t); 

t = westok(NULL, L",", &ptrl);  /* t points to the token L"?b"x/ 
printf("t = '%1s'\n", t); 

t = westok(str2, L" \t,", &ptr2); /* t is a null pointer */ 
printf("t = '%ls'\n", t); 

t = westok(NULL, L"#,", &ptr1); /* t points to the token L"c" */ 
printf("t = '%ls'\n", t)s; 

t = westok(NULL, L"?", &ptr1); /* t is a null pointer */ 
printf("t = '%1s'\n", t); 

return 0; 


[BRK K KKK KEI KK ERK KEI KKK AKER KKK AKER IKKE AK KBAR EA KKK EK KIER AKER ARE 
The output should be similar to: 


lait 
1b! 
' 
‘! 


Pr CF et oct 
tou Wow ou 


t 
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} 


Related Information 


wcstoul() — wcstoull() — Convert WideCharacter String to Unsigned 
Long and Unsigned Long Long Integer 


430 


Format (wcstoul ()) 


#include <wchar.h> 
unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base); 


Format (wcstoull ()) 


#include <wchar.h> 
unsigned long long int wcstoull(const wchar_t *nptr, wchar_t **endptr, int base); 


Language Level: ANSI 
Description 


The westoul() function converts the initial portion of the wide-character string 
pointed to by nptr to an unsigned long integer value. The nptr parameter points to 
a sequence of wide characters that can be interpreted as a numerical value of type 
unsigned long int. The wcstoul() function stops reading the string at the first wide 
character that it cannot recognize as part of a number. This character can be the 
wchar_t null character at the end of the string. The ending character can also be 
the first numeric character greater than or equal to the base. 
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The behavior of the westoul() function is affected by the LC_CTYPE category of 
the current locale. This function is available only when LOCALETYPE(*LOCALE) 
or LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


The westoul1() subroutine converts a wide-character string to an unsigned long 
long integer. The wide-character string is parsed to skip the initial space characters 
(as determined by the iswspace subroutine). Any non-space character signifies the 
start of a subject string that may form an unsigned long long int in the radix 
specified by the base parameter. The subject sequence is defined to be the longest 
initial substring that is an unsigned long long int of the expected form. 


If the value of the endptr parameter is not null, then a pointer to the character that 
ended the scan is stored in endptr. If an unsigned long long integer cannot be 
formed, the value of the endptr parameter is set to that of the nptr parameter. 


If the base parameter is a value between 2 and 36, the subject sequence’s expected 
form is a sequence of letters and digits representing an unsigned long long integer 
whose radix is specified by the base parameter. This sequence optionally is 
preceded by a positive (+) or negative (-) sign. Letters from a (or A) to z (or Z) 
inclusive are ascribed the values 10 to 35; only letters whose ascribed values are 
less than that of the base parameter are permitted. If the base parameter has a value 
of 16, the characters 0x or 0X optionally precede the sequence of letters and digits, 
following the positive (+) or negative (-) sign, if present. 


If the value of the base parameter is 0, the string determines the base. Therefore, 
after an optional leading sign, a leading 0 indicates octal conversion, and a leading 
Ox or OX indicates hexadecimal conversion. 


The value of errno may be set to EINVAL (endptr is null, no numbers are found, or 
base is invalid), or ERANGE (converted value is outside the range). 


Return Value 


The westoul() function returns the converted unsigned long integer value. If no 
conversion could be performed, the wcstoul() function returns 0. If the correct 
value is outside the range of representable values, The wcstoul() function returns 
ULONG_MAX and sets errno to ERANGE. If the string nptr points to is empty or 
does not have the expected form, no conversion is performed, and the value of 
nptr is stored in the object pointed to by endptr, provided that endptr is not a null 
pointer. 


Upon successful completion, the wcstoul1() subroutine returns the converted 
value. If no conversion could be performed, 0 is returned, and the errno global 
variable is set to indicate the error. If the correct value is outside the range of 
representable values, wcstoul1() subroutine returns a value of 
ULONG_LONG_MAX. 


Example that uses wcstoul () 


This example uses the wcstoul() function to convert the string wes to an unsigned 
long integer value. 


#include <stdio.h> 
#include <wchar.h> 


#define BASE 2 
int main(void) 
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wchar_t *wcs = L"1000e13 camels"; 
wcehar_t *endptr; 
unsigned long int answer; 


answer = wcstoul(wcs, &endptr, BASE); 
printf("The input wide string used: '%1s’\n" 
"The unsigned long int produced: %lu\n" 
"The substring of the input wide string that was not" 
"converted to unsigned long: '%1s'\n", wcs, answer, endptr); 
return 0; 


[BRK A KKK KK ER KK ERK KERIKERI KEI KK AKIRA KKK AKEK KKK IKKE AIK AKIRA A RE 
The output should be similar to: 


The input wide string used: 1000e13 camels 
The unsigned long int produced: 8 
The substring of the input wide string that was not converted to 


unsigned long: e13 camels 
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} 


Related Information 


wcswcs() — Locate Wide-Character Substring 
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Format 

#include <wcstr.h> 

wchar_t *wcswcs(const wchar_t *stringl, const wchar_t *string2); 

Language Level: XPG4 

Description 

The wcswes() function locates the first occurrence of string2 in the wide-character 
string pointed to by string1. In the matching process, the weswcs() function ignores 
the wchar_t null character that ends string2. 


Return Value 


The wcswcs() function returns a pointer to the located string or NULL if the string 
is not found. If string2 points to a string with zero length, weswcs() returns string1. 


Example that uses wcswcs() 


This example finds the first occurrence of the wide character string pr in buffer1. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
wehar_t buffer1[SIZE] = L"computer program"; 
wchar_t * ptr; 
wchar_t * wch = L"pr"; 


ptr = wceswcs( bufferl, wch ); 


printf( "The first occurrence of %ls in '%ls' is '%ls'\n", 
weh, bufferl, ptr ); 
} 


[KEKRKRKEKEREKKR Output should be similar tO: ***kXKKKKKKEKKKKKK 


The first occurrence of pr in ‘computer program' is 'program' 


*/ 


Related Information 


wcswidth() — Determine the Display Width of a Wide Character String 


Format 


#include <wchar.h> 
int wceswidth (const wchar_t *wcs, size_t n); 


Language Level: XPG4 

Thread Safe: YES. 

Description 

The weswidth() function determines the number of printing positions that a 
graphic representation of m wide characters (or fewer that n wide characters if a 
null wide character is encountered before n wide characters have been exhausted) 
in the wide string pointed to by wes occupies on a display device. The number is 


independent of its location on the device. 


The value of errno may be set to EILSEQ (invalid wide character), or ECONVERT 
(conversion error). 
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Return Value 


The wcswidth() function either returns: 
* 0, if wes points to a null wide character; or 


* the number of printing positions occupied by the wide string pointed to by wes; 
or 


* -1, if any wide character in the wide string pointed to by wes is not a printing 
wide character. 


The behavior of the wcswidth() function is affected by the LC_CTYPE category. 


Example that uses wcswidth() 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 
wchar_t *wcs = L"ABC"; 


printf("wcs has a width of: %d\n", wcswidth(wcs,3))3; 


} 


[KRKKKKEKEKEKTNO output is as FOl LOWS kx KKKKKKKKKKK / 


/* 


/* wes has a width of: 3 */ 
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Related Information 


wcsxfrm() — Transform a Wide-Character String 
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Format 


#include <wchar.h> 
size_t wesxfrm (wchar_t *wcsl, const wchar_t *wcs2, size_t n); 


Language Level: XPG4 

Description 

The wesxfrm() function transforms the wide-character string pointed to by wes2 to 

values which represent character collating weights and places the resulting 

wide-character string into the array pointed to by wes1. 

Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 
The behavior of this wide-character function is affected by the 


LC_COLLATE category of the current locale. 


Return Value 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


The wesxfrm() function returns the length of the transformed wide-character string 
(not including the ending null wide character code). If the value returned is n or 
more, the contents of the array pointed to by wes1 are indeterminate. 


If wesxfrm() is unsuccessful, errno is changed. The value of errno may be set to 
EINVAL (the wes1 or wes2 arguments contain characters which are not available in 
the current locale). 


Example that uses wcsxfrm() 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 


wchar_t *wcs; 
wchar_t buffer[80]; 
int length; 


printf("Type in a string of characters.\n "); 

wes = fgetws(buffer, 80, stdin); 

length = wcsxfrm(NULL, wes, Q); 

printf("You would need a %d element array to hold the wide string\n", length); 
printf("\n\n%S\n\n transformed according", wes); 

printf(" to this program's locale. \n"); 


} 


Related Information 


wctob() — Convert Wide Character to Byte 


Format 


#include <stdio.h> 
#include <wchar.h> 
int wctob(wint_t wc); 


Language Level: ANSI 
Description 


The wctob() function determines whether we corresponds to a member of the 
extended character set, whose multibyte character has a length of 1 byte when in 
the initial shift state. The behavior of the wctob() function is affected by the 
LC_CTYPE category of the current locale. This function is available only when 
LOCALETYPE(*LOCALE) is specified on the compilation command. 


If a program is compiled with LOCALETYPE(#*LOCALEUCS2), the wctob() 
function will behave as if the program was compiled with 
LOCALETYPE(*LOCALE), because the wctob() function does not support 
UNICODE. 


Return Value 


If c corresponds to a multibyte character with a length of 1 byte, the wctob() 
function returns the single-byte representation. Otherwise, it returns EOF. 
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Example that uses wctob() 


This example uses the wctob() function to test if the wide character A is a valid 
single-byte character. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 
wint_t we = L'A'; 


if (wctob(wc) == wc) 
printf("%lc is a valid single byte character\n", wc); 


else 
printf("%lc is not a valid single byte character\n", wc); 
return 0; 


[BRK AK KER KK EAR KERR KER AKER AKIRA KEIRA KEK KIKI KERR 
The output should be similar to: 


A is a valid single byte character 
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} 


Related Information 


wctomb() — Convert Wide Character to Multibyte Character 
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Format 


#include <stdlib.h> 
int wctomb(char *string, wchar_t character); 


Language Level: ANSI 

Description 

Thread Safe: NO. Use wertomb() instead. 

The wcetomb() function converts the wchar_t value of character into a multibyte 
array pointed to by string. If the value of character is 0, the function is left in the 
initial shift state. At most, the wctomb() function stores MB_CUR_MAxX characters 


in string. 


The conversion of the wide character is the same as described in wcstombs(). See 
this function for a UNICODE example. 


Return Value 


The wctomb() function returns the length in bytes of the multibyte character. The 
value -1 is returned if character is not a valid multibyte character. If string is a 
NULL pointer, the wctomb() function returns nonzero if shift-dependent encoding 
is used, or 0 otherwise. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Example that uses wctomb() 
This example converts the wide character c to a multibyte character. 


#include <stdio.h> 
#include <stdlib.h> 
#include <wcstr.h> 


#define SIZE 40 


int main(void) 

{ 
static char buffer[ SIZE ]; 
wchar_t wch = L'c'; 
int length; 


length = wctomb( buffer, wch ); 
printf( "The number of bytes that comprise the multibyte " 
"character is %i\n", length ); 
printf( "And the converted string is \"%s\"\n", buffer ); 
} 


[KEKRKEKEKEREKKR Output should be similar tO: ***kXKKKKKKEKKKKEK 
The number of bytes that comprise the multibyte character is 1 

And the converted string is "c" 

x/ 


Related Information 


wctrans() —Get Handle for Character Mapping 


Format 

#include <wctype.h> 

wetrans_t wctrans(const char *property) ; 

Language Level: ANSI 

Description 

The wctrans() function constructs a value with type wctrans_t. This value 
describes a mapping between wide characters identified by the string argument 
property. The two strings listed under the towctrans() function description shall be 


valid in all locales as property arguments to the wctrans() function. 


Return Value 
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If property identifies a valid mapping of wide characters according to the 
LC_CTYPE category of the current locale, the wctrans () function returns a nonzero 
value that is valid as the second argument to the towctrans() function. Otherwise, 
it returns 0. 


Example that uses wctrans () 


This example translates the lowercase alphabet to uppercase, and back to 
lowercase. 


#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <wchar.h> 
#include <wctype.h> 


int main() 

{ 
char *alpha = "abcdefghijkIlmnopgqrstuvwxyz"; 
char *tocase[2] = {"toupper", "tolower"}; 
wchar_t *wcalpha; 
int i, js 
size_t alphalen; 


alphalen = strlen(alpha)+1; 
wealpha = (wchar_t *)malloc(sizeof(wchar_t)*alphalen) ; 


mbstowcs(wcalpha, alpha, 2*alphalen); 

for (i=0; i<2; ++i) { 
printf("Input string: %1s\n", wcalpha); 
for (j=0; j 
for (j=0; j 


Related Information 


wctype() — Get Handle for Character Property Classification 
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Format 


#include <wctype.h> 
wetype_t wctype(const char *property) ; 


Language Level: XPG4 
Description 


The wctype() function is defined for valid property names as defined in the 
current locale. The property is a string that identifies a generic character class for 
which locale specific type information is required. The function returns a value of 
type wctype_t, which can be used as the second argument to a call of the 
iswctype() function. 


The wctype() function determines values of wctype_t according to rules of the 
coded character set that are defined by character type information in the program’s 
locale (category LC_CTYPE). Values that are returned by the wctype() are valid 
until a call to setlocale() that changes the category LC_CTYPE. 
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Return Value 

The wctype() function returns zero if the given property name is not valid for the 
current locale (category LC_CTYPE or LC_UCS2_CTYPE). Otherwise it returns a 
value of type wctype_t that can be used in calls to iswctype(). 


Example that uses wctype() 
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#include <wchar.h> 


#define UPPER_LIMIT OxFF 
int  main(void) 


{ 
int wes 
for (we = 03 we <= 
printf("%#4x ",  we)s 

. printf("%c", iswctype(wc, 
Ki printf("%s",  iswctype(wc, 
= printf("%s",  iswctype(we, 
i printf("%s",  iswctype(wc, 
- printf("%s",  iswctype(we, 
“ printf("%s",  iswctype(wc, 
ik printf("%s",  iswctype(we, 
= printf("%s",  iswctype(we, 
i printf("%s",  iswctype(we, 
is printf("%s",  iswctype(we, 
ie printf("%s",  iswctype(we, 
ik printf("%s",  iswctype(we, 
_ printf("%s", iswctype(wc, 


putchar('\n'); 
} 


return 0; 


[RRR KKK AKER AKER A KKK A KKK IKKE KK KKK KK IKKE AKER IKKE AK KAKI R AKER EK 


The output should be 


Oxlf C 
0x20 B 
0x21 ! 

@x22 " 

0x23. # 
0x24 $ 
0x25 % 
0x26 & 
0x27 ' 
0x28 ( 
0x29) 
Ox2a* 
Ox2b + 
Ox2c 3 
Ox2d_s- 
0x2e 
Ox2f 
0x30 
0x31 
0x32 
0x33 
0x34 
0x35 


[<p MQMDODDDIDDIDMIDMDD|DM 


OFWNFrO™s 
> 
= 

ww iw ww} 
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UPPER_LIMIT; 


[<p 


wetype("print")) 
wetype("alnum") ) 
wctype("alpha")) 
wetype("blank")) 
wetype("cntr1")) 
wetype("digit")) 
wctype("graph")) 
wetype("lower") ) 
wetype("punct")) 
wctype("space")) 
wetype("print")) 


wctype ("upper") ) 


wce++) 


? 


wetype("xdigit")) ? 


similar to 


S PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
PU PR 
G PR 
G PR 
G PR 
G PR 
G PR 
G PR 


wc 


"AN" 


mau 


"pu 


uc 


"pe 


"gu 


a ca 


"py" 


"gu 


"DRY 


wyn 


nyu 


>< >< >< >< >< >< 


Related Information 


wewidth() — Determine the Display Width of a Wide Character 


Format 


#include <wchar.h> 
int wewidth (const wint_t wc); 


Language Level: XPG4 
Thread Safe: YES. 
Description 


The wewidth() function determines the number of printing positions that a graphic 
representation of wc occupies on a display device. Each of the printing wide 
characters occupies its own number of printing positions on a display device. The 
number is independent of its location on the device. 


Note: This function is accessible only if LOCALETYPE(*LOCALE) or 
LOCALETYPE(*LOCALEUCS2) is specified on the compilation command. 


Return Value 


The wewidth() function either returns: 

¢ 0, if we is a null wide character; or 

* the number of printing position occupied by we; or 
* -1, if we is not a printing wide character. 


The behavior of the wewidth() function is affected by the LC_CTYPE category of 
the current locale. If the program is compiled with LOCALETYPE(*LOCALEUCS2), 
the wide character properties are those defined by the LC_UCS2_CTYPE category 
of the current locale. 


Example that uses wcewidth() 


#include <stdio.h> 
#include <wchar.h> 


int  main(void) 
wint_t we = L'A's 


printf("%lc has a width of d\n", wc,  wewidth(wc)); 
return 0; 


[BRK R KK RKKE AK KER AKER AKER KK EKA K KAKA KAKA KIKI KA KKK K 
The output should be similar’ to 
A has a width of 1 
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} 


Related Information 
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wfopen() —Open Files 


Format 


#include <ifs.h> 
FILE * wfopen(const wchar_t *filename,const wchar_t *mode); 


Language Level: ILE C Extension 
Thread Safe: Yes 
Description 


The wfopen() function works like the fopen() function, except: 
* wfopen() accepts file name and mode as wide characters. 


* wfopen() assumes CCSID 13488 if neither CCSID nor codepage keyword is 
specified. 


The wfopen() function is made available by specifying SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALEUCS2) on the compilation command. 


wmemchr() —Locate Wide Character in Wide-Character Buffer 


Format 

#include <wchar.h> 

wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n); 

Language Level: ANSI 

Description 

The wmemchr() function locates the first occurrence of c in the initial n wide 
characters of the object pointed to by s. If n has the value 0, the wmemchr() function 
finds no occurrence of c, and returns a NULL pointer. 


Return Value 


The wmemchr() function returns a pointer to the located wide character, or a NULL 
pointer if the wide character does not occur in the object. 


Example that uses wmemchr () 


This example finds the first occurrence of ’A’ in the wide-character string. 
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#include <stdio.h> 
#include <wchar.h> 


main() 

{ 
wehar_t *in = L"1234ABCD"; 
wcehar_t «ptr; 
wehar_t fnd = L'A'; 


printf("\nEXPECTED: ABCD"); 
ptr = wmemchr(in, L'A', 6); 
if (ptr == NULL) 
printf("\n** ERROR ** ptr is NULL, char L'A' not found\n"); 
else 
printf("\nRECEIVED: %1s \n", ptr); 
} 


Related Information 


wmemcmp() —Compare Wide-Character Buffers 


Format 

#include <wchar.h> 

int wmemcmp(const wchar_t *sl, const wchar_t *s2, size_t n); 

Language Level: ANSI 

Description 

The wmemcmp() function compares the first n wide characters of the object pointed 
to by s1 to the first n wide characters of the object pointed to by s2. If n has the 
value 0, the wmemcmp() function returns 0. 


Return Value 


The wmemcmp() function returns a value according to the relationship between the 
two strings, s7 and s2: 


Integer Value Meaning 

Less than 0 s1 less than s2 

0 s1 equal to s2 
Greater than 0 s1 greater than s2 


Example that uses wmemcmp () 
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This example compares the wide-character string in to out using the 
wmemcmp () function. 


#include <wchar.h> 
#include <stdio.h> 
#include <locale.h> 


main() 

{ 
int rcs; 
wehar_t *in = L"12345678"; 
wehar_t *out = L"12AAAAAB"; 
setlocale(LC_ALL, "POSIX"); 


printf("\nGREATER is the expected result"); 
rc = wmemcmp(in, out, 3); 


if (rc == 0) 

printf("\nArrays are EQUAL %1s %1s \n", in, out); 
else 
{ 
if (rc > 0) 

printf("\nArray %1s GREATER than %1s \n", in, out); 
else 


printf("\nArray %1s LESS than %1s \n", in, out); 
} 


[RRR IKKE KKK ERK KERIKERI KEK AKKE IKKE IKKE AK KER AK AK EA EKER 


The output should be: 


GREATER is the expected result 
Array 12345678 GREATER than 12AAAAAB 
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} 


Related Information 


wmemcpy() —Copy Wide-Character Buffer 
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Format 


#include <wchar.h> 
wchar_t *wmemcpy(wchar_t *sl, const wchar_t *s2, size_t n); 


Language Level: ANSI 

Description 

The wmemcpy() function copies n wide characters from the object pointed to by s2 
to the object pointed to by s1. If s1 and s2 overlap, the result of the copy is 
unpredictable. If n has the value 0, the wmemcpy() function copies 0 wide 


characters. 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Return Value 
The wmemcpy() function returns the value of s17. 
Example that uses wmemcpy () 


This example copies the first four characters from out to in. In the expected output, 
the first four characters in both strings will be "ABCD". 


#include <wchar.h> 
#include <stdio.h> 


main() 

{ 
wehar_t *in = L"12345678"; 
wchar_t *out = L"ABCDEFGH"; 
wchar_t «ptr; 


printf("\nExpected result: First 4 chars of in change"); 
printf(" and are the same as first 4 chars of out"); 
ptr = wmemcpy(in, out, 4); 


if (ptr == in) 

printf("\nArray in %1s array out %1s \n", in, out); 
else 
{ 


printf("\n*** ERROR ***"); 
printf(" returned pointer wrong"); 
} 

} 


Related Information 


wmemmove() — Copy Wide-Character Buffer 


Format 
#include <wchar.h> 


wchar_t *wmemmove(wchar_t *sl, const wchar_t *s2, size_t n); 

Language Level: ANSI 

Description 

The wmemmove() function copies n wide characters from the object pointed to by s2 
to the object pointed to by s1. Copying takes place as if the n wide characters from 


the object pointed to by s2 are first copied into a temporary array, of n wide 
characters, that does not overlap the objects pointed to by s1 or s2. Then, the 
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wmemmove() function copies the n wide characters from the temporary array into 
the object pointed to by s1. If n has the value 0, the wmemmove() function copies 0 
wide characters. 


Return Value 
The wmemmove() function returns the value of s1. 
Example that uses wmemmove () 


This example copies the first five characters in a string to overlay the last five 
characters in the same string. Since the string is only nine characters long, the 
source and target overlap. 


#include <wchar.h> 
#include <stdio.h> 


void main() 


{ 
wehar_t *theString = L"ABCDEFGHI"; 


printf("\nThe original string: %1s \n", theString); 
wmemmove(theStringt4, theString, 5); 
printf("\nThe string after wmemmove: %1s \n", theString) ; 


returns 


[BRK R KKK KK EAR KER AKER KKK A KKK IKKE IKKE KK KKK KKK KKK KK ERK 


The output should be: 


The original string: ABCDEFGHI 
The string after wmemmove: ABCDABCDE 
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} 


Related Information 


wmemset() — Set Wide Character Buffer to a Value 
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Format 

#include <wchar.h> 

wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n); 

Language Level: ANSI 

Description 

The wmemset() function copies the value of c into each of the first n wide 
characters of the object pointed to by s. If n has the value 0, the wmemset() function 


copies 0 wide characters. 


Return Value 
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The wmemset() function returns the value of s. 
Example that uses wmemset () 


This example sets the first 6 wide characters to the wide character ’A’. 


#include <wchar.h> 
#include <stdio.h> 


void main() 


wehar_t *in = L"1234ABCD"; 
wchar_t «ptr; 


printf("\nEXPECTED: AAAAAACD") ; 
ptr = wmemset(in, L'A', 6); 


if (ptr == in) 
printf("\nResults returned - %1s \n", ptr); 
else 


printf("\n** ERROR ** wrong pointer returned\n") ; 
} 
} 


Related Information 


wprintf() — Format Data as Wide Characters and Print 
Format 
#include <wchar.h> 
int wprintf(const wchar_t *format,...); 
Language Level: ANSI 
Thread Safe: YES. 
Description 


A wprintf(format, ... ) is equivalent to fwprintf(stdout, format, ... ). 


Note: This function is available only when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) are specified on the compilation command. 


Return Value 


The wprintf() function returns the number of wide characters transmitted. If an 
output error occurred, the wprintf() function returns a negative value. 


Example that uses wprintf () 
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This example prints the wide character a. Date and time may be formatted 
according to your locale’s representation. The output goes to stdout. 


#include <wchar.h> 
#include <stdarg.h> 
#include <locale.h> 


int main(void) 
{ 
setlocale(LC_ALL, "POSIX"); 


wprintf (L"%c\n", L'a'); 
return(0); 


/* A long 'a' is written to stdout *«/ 


Related Information 


wscanf() — Read Data Using Wide-Character Format String 
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Format 

#include <wchar.h> 

int wscanf(const wchar_t *format,...); 
Language Level: ANSI 


Description 


The wscanf() function is equivalent to the fwscanf() function with the argument 
stdin interposed before the arguments of the wscanf() function. 


Note: This function is available only when SYSIFCOPT(*IFSIO) and 
LOCALETYPE(*LOCALE) or LOCALETYPE(*LOCALEUCS2) are specified 
on the compilation command. 


Return Value 


If an input failure occurs before any conversion, the wscanf() function returns the 
value of the macro EOF. 


Otherwise, the wscanf() function returns the number of input items assigned. It 
can be fewer than provided for, or even zero, in the event of an early matching 


failure. 


Example that uses wscanf () 
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This example scans various types of data. 


#include <stdio.h> 
#include <wchar.h> 


int main(void) 


{ 


int is; 
float fp; 
char c,s[81]; 


printf("Enter an integer, a real number, a character and a string : \n"); 
if (wscanf(L"%d %f %c %s", &i, &fp,&c, s) != 4) 


printf("Not all of the fields were not assigned\n"); 


else { 


} 


printf("integer = %d\n", i); 
printf("real number = %f\n", fp); 
printf("character = %c\n", c); 
printf("string = %s\n", s); 


return 0; 
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The output should be similar to: 


Enter an integer, a real number, a character and a string : 
12 2.5 a yes 
integer = 12 
real number = 
character =a 
string = yes 


2.500000 
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Related Information 
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450 ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Chapter 3. Run-Time Considerations 


This chapter provides information on: 


* Exception and condition management 


* Interlanguage data type compatibility 
* CCSID (Coded Character Set Identifier) source file conversion 


errno Macros 


The following table lists which error macros the ILE C library functions can set. 


Table 12. errno Macros 


Error Macro 


Description 


Set by Function 


EBADDATA The message data is not perror, strerror 
valid. 
EBADF The catalog descriptor is not | catclose, catgets, clearerr, 
valid. fgetc, fgetpos, fgets, fileno, 
freopen, fseek, fsetpos, getc, 
rewind 
EBADKEYLN The key length specified is _Rreadk, _Rlocate 
not valid. 
EBADMODE The file mode specified is fopen, freopen, _Ropen 
not valid. 
EBADNAME Bad file name specified. fopen, freopen, _Ropen 
EBADPOS The position specified is not | fsetpos 
valid. 
EBADSEEK Bad offset for a seek fgetpos, fseek 
operation. 
EBUSY The record or file is in use. _| perror, strerror 
ECONVERT Conversion error. westomb, wcswidth 
EDOM Domain error in math acos, asin, atan2, cos, exp, 
function. fmod, gamma, hypot, j0, j1, 
jn, yO, yl, yn, log, log10, 
pow, sin, strtol, strtoul, sqrt, 
tan 
EGETANDPUT An illegal read operation fgetc, fread, getc, getchar 
occurred after a write 
operation. 
EILSEQ The character sequence does _ | fgetwc, fgetws, getwc, 
not form a valid multibyte mblen,mbrlen, mbrtowc, 
character. mbsrtowcs, mbstowcs, 
mbtowc, printf, scanf, 
ungetwc, wcertomb, 
wcsrtombs, wcstombs, 
wctomb, wcswidth, wewidth 
EINVAL The signal is not valid. printf, scanf, signal, swprintf, 


swscanf, westol, westoll, 
westoul, wcstoull 
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Table 12. errno Macros (continued) 


Error Macro 


Description 


Set by Function 


EIO 


Consecutive calls of I/O 
occurred. 


1/O 


EIOERROR A non-recoverable I/O error | All I/O functions 

occurred. 

EIORECERR A recoverable I/O error All I/O functions 

occurred. 

ENODEV Operation attempted on a fgetpos, fsetpos, fseek, ftell, 

wrong device. rewind 

ENOENT File or library is not found. | perror, strerror 

ENOPOS No record at specified fsetpos 

position. 
ENOREC Record not found. fread, perror, strerror 
ENOTDLT File is not opened for delete | _Rdelete 

operations. 

ENOTOPEN File is not opened. clearerr, fclose, fflush, 
fgetpos, fopen, freopen, 
fseek, ftell, setbuf, setvbuf, 
_Ropen, _Rclose 

ENOTREAD File is not opened for read fgetc, fread, ungetc, _Rreadd, 

operations. _Rreadf, _Rreadindv, 
Rreadk, _Rreadl, _Rreadn, 
_Rreadnc, _Rreadp, _Rreads, 
_Rlocate 

ENOTUPD File is not opened for update |_Rrlslck, _Rupdate 

operations. 

ENOTWRITE File is not opened for write | fputc, fwrite, _Rwrite, 

operations. _Rwrited, _Rwriterd 

ENUMMBRS More than 1 member. ftell 

ENUMRECS Too many records. ftell 

EPAD Padding occurred on a write | fwrite 

operation. 

EPERM Insufficient authorization for | perror, strerror 

access. 

EPUTANDGET An illegal write operation fputc, fwrite, fputs, putc, 

occurred after a read putchar 
operation. 
ERANGE Range error in math cos, cosh, gamma, exp, j0, j1, 
function. jn, yO, y1, yn, log, log10, 
Idexp, pow, sin, sinh, strtod, 
strtol, strtoul, tan, westol, 
westoll, westoul, westoull, 
westod 
ERECIO File is opened for record fgetc, fgetpos, fputc, fread, 
I/O, so character-at-a-time fseek, fsetpos, ftell 
processing functions cannot 
be used. 

ESTDERR stderr cannot be opened. feof, ferror, fgetpos, fputc, 


fseek, fsetpos, ftell, fwrite 
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Table 12. errno Macros (continued) 


Error Macro Description Set by Function 

ESTDIN stdin cannot be opened. fgetc, fgetpos, fread, fseek, 
fsetpos, ftell 

ESTDOUT stdout cannot be opened. fgetpos, fputc, fseek, fsetpos, 
ftell, fwrite 

ETRUNC Truncation occurred on I/O_ | Any I/O function that reads 


operation. or writes a record sets errno 
to ETRUNC. 


errno Values for Integrated File System Enabled C Stream I/O 


The following table describes the possible settings when using integrated file 
system enabled stream I/O. 


Table 13. errno Values for IFS Enabled C Stream I/O 


C Stream 

Function Possible errno Values 

clearerr EBADF 

fclose EAGAIN, EBADF, EIO, EUNKNOWN 

feof EBADF 

ferror EBADF 

fflush EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 

fgetc EBADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD, 

fgetpos EACCESS, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOSYSRSC, EUNATCH, EUNKNOWN 

fgets EBADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 

fgetwe EBADEF, EILSEQ 

fgetws EBADEF, EILSEQ 

fopen EAGAIN, EBADNAME, EBADF, ECONVERT, EDAMAGE, EEXITS, 
EFAULT, EINVAL, EIO, EISDIR, ELOOP, ENOENT, ENOMEM, ENOSPC, 
ENOSYS, ENOSYSRSC, ENOTDIR 

fprintf EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 

fputc EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 

fputs EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 

fread EBADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 
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Table 13. errno Values for IFS Enabled C Stream I/O (continued) 


C Stream 
Function 


freopen 


Possible errno Values 


EACCES, EAGAIN, EBADNAME, EBADF, EBUSY, ECONVERT, 
EDAMAGE, EEXITS, EFAULT, EINVAL, EIO, EISDIR, ELOOP, EMFILE, 
ENAMETOOLONG, ENFILE, ENOENT, ENOMEM, ENOSPC, ENOSYS, 
NOSYSRSC, ENOTDIR 


fscanf 


BADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
NNOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 


fseek 


ACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EINVAL, EIO, ENOENT, 
NNOSPC, ENOSYSRSC, ESPIPE, EUNKNOWN, EFAULT, EPERM, 
UNATCH, EUNKNOWN 


fsetpos 


ACCES, EAGAIN, ABADF, EBUSY, EDAMAGE, EINVAL, EIO, ENOENT, 
NNOSPC, ENOSYSRSC, ESPIPE, EUNKNOWN, EFAULT, EPERM, 
EUNATCH, EUNKNOWN 


eo eon eses em es mesm mes! 


ftell 


EACCESS, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOSYSRSC, EUNATCH, EUNKNOWN 


fwrite 


ACCESS, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
NNOSYSRSC, EUNATCH, EUNKNOWN 


getc 


BADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
NNOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 


getchar 


BADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
NNOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 


gets 


BADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
NNOMEM, EUKNOWN, EGETANDPUT, EDOM, ENOTREAD 


eo eoie eres eres es iees| 


getwc 


EBADF, EILSEQ 


perror 


EBADF 


printf 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EILSEQ, EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


putc 


putchar 


puts 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


remove 


EACCES, EAGAIN, EBADNAME, EBADF, EBUSY, ECONVERT, 
EDAMAGE, EEXITS, EFAULT, EINVAL, EIO, EISDIR, ELOOP, 
ENAMETOOLONG, ENOENT, ENOMEM, ENOSPC, ENOTDIR, EPERM, 
EROOBJ, EUNKNOWN, EXDEV 


rename 


EACCES, EAGAIN, EBADNAME, EBUSY, ECONVERT, EDAMAGE, 
EEXIST, EFAULT, EINVAL, EIO, EISDIR, ELOOP, ENAMETOOLONG, 
ENOTEMPTY, ENOENT, ENOMEM, ENOSPC, ENOTDIR, EMLINK, 
EPERM, EUNKNOWN, EXDEV 


rewind 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EINVAL, EIO, ENOENT, 
ENOSPC, ENOSYSRSC, ESPIPE, EUNKNOWN, EFAULT, EPERM, 
EUNATCH, EUNKNOWN 
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Table 13. errno Values for IFS Enabled C Stream I/O (continued) 


C Stream 
Function 


scanf 


setbuf 


Possible errno Values 


EBADF, EACCES, EAGAIN, EBUSY, EDAMAGE, EFAULT, EILSEQ, 
EINVAL, EIO, ENOMEM, EUKNOWN, EGETANDPUT, EDOM, 
ENOTREAD 


EBADF, EINVAL, EIO 


setvbuf 


tmpfile 


EBADF, EINVAL, EIO 


EACCES, EAGAIN, EBADNAME, EBADF, EBUSY, ECONVERT, 
EDAMAGE, EEXITS, EFAULT, EINVAL, EIO, EISDIR, ELOOP, EMFILE, 
ENAMETOOLONG, ENFILE, ENOENT, ENOMEM, ENOSPC, ENOSYS, 
ENOSYSRSC, ENOTDIR, EPERM, EROOBJ, EUNKNOW N, EXDEV 


tmpnam 


EACCESS, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EINVAL, EIO, 
ENOENT, ENOSYSRSC, EUNATCH, EUNKNOWN 


ungetc 


EBADEF, EIO 


ungetwc 
vfprintf 


EBADEF, EILSEQ 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


vprintf 


EACCES, EAGAIN, EBADF, EBUSY, EDAMAGE, EFAULT, EFBIG, 
EINVAL, EIO, ENOMEM, ENOSPC, ETRUNC, EUNKNOWN, 
EPUTANDGET, ENOTWRITE, EPAD 


Record Input and Output Error Macro to Exception Mapping 


The following table describes what occurs if the signal SIGIO is raised. Only 
*ESCAPE, *NOTIFY, and *STATUS messages are monitored. 


Table 14. Record Input and Output Error Macro to Exception Mapping 


Description 


Messages (_EXCP_MSGID) | errno setting 


*STATUS and *NOTIFY CPF4001 to CPF40FF, errno is not set, a default 


CPF4401 to CPF44FF, reply is returned to the 
CPF4901 to CPF49FF, operating system. 
CPF5004 


Recoverable I/O error CPF4701 to CPF47FF, EIORECERR 


Non-recoverable I/O error? | CPF4101 to CPF41FE, EIOERROR 


CPF4801 to CPF48FF, 
CPF5001 to CPF5003, 
CPF5005 to CPF50FF, 


CPF4201 to CPF42FF, 
CPF4301 to CPF43FF, 
CPF4501 to CPF45FF, 
CPF4601 to CPF46FF, 
CPF5101 to CPF51FF, 
CPF5201 to CPF52FF, 
CPF5301 to CPF53FF, 
CPF5401 to CPF54FF, 
CPF5501 to CPF55FF, 
CPF5601 to CPF56FF 


operation 


Truncation occurred at I/O C2M3003 ETRUNC 


File is not opened C2M3004 ENOTOPEN 
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Table 14. Record Input and Output Error Macro to Exception Mapping (continued) 


Description Messages (_EXCP_MSGID) | errno setting 
File is not opened for read C2M3005 ENOTREAD 
operations 

File is not opened for write | C2M3009 ENOTWRITE 
operations 

Bad file name specified C2M3014 EBADNAME 
The file mode specified is C2M3015 EBADMODE 
not valid 

File is not opened for update | C2M3041 ENOTUPD 
operations 

File is not opened for delete | C2M3042 ENOTDLT 
operations 

The key length specified is C2M3044 EBADKEYLN 
not valid 

A non-recoverable I/O error |C2M3101 EIOERROR 
occurred 

A recoverable I/O error C2M3102 EIORECERR 
occurred 


Note: 


SIG_IGN. 


— ICF Programming 


— ADTS/400: Advanced Printer Function 
Application Display Programming 


Tape and Diskette Device Programming 


¢ | The error is percolated to the user, therefore the user’s direct monitor handlers, ILE C 
condition handlers and signal handler may get control. The initial setting for SIGIO is 


* 7 The type of device determines whether the error is recoverable or not recoverable. The 
following IBM publications contain information about recoverable and non-recoverable 
system exceptions for each specific file type: 


The following table shows the initial state of the C signal values and their 
handling action definitions when SYSIFCOPT(*NOASYNCSIGNAL) is specified on 
the compilation command. SIG_DFL always percolates the condition tothe handler. 
Resume indicates the exception is handled, and the application continues. 


Table 15. Handling Action Definitions for Signal Values 


Return from 
Signal Value Initial State SIG_DFL SIG_IGN Handler 
SIGABRT’ SIG_DFL Percolate Ignore Resume 
SIGALL? SIG_DFL Percolate Ignore Resume 
SIGFPE SIG_DFL Percolate Ignore® Resume* 
SIGILL SIG_DFL Percolate Ignore® Resume? 
SIGINT SIG_DFL Percolate Ignore Resume 
SIGIO SIG_IGN Percolate Resume 
SIGOTHER SIG_DFL Percolate Ignore® Resume* 
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Table 15. Handling Action Definitions for Signal Values (continued) 


Return from 
Signal Value Initial State SIG_DFL SIG_IGN Handler 
SIGSEGV SIG_DFL Percolate Ignore® Resume* 
SIGTERM SIG_DFL Percolate Ignore Resume 
SIGUSR1 SIG_DFL Percolate Ignore Resume 
SIGUSR2 SIG_DFL Percolate Ignore Resume 
Note: 


* 1 Can only be signaled by the raise() function or the abort() function 

* ? SIGALL cannot be signaled by the raise() function. 

* 3 If the value of the signal is SIGFPE, SIGILL or SIGSEGV the behavior is undefined. 
* 4+ Tf the signal is hardware-generated, then the behavior undefined. 


The following table shows the initial state of the C signal values and their 
handling action definitions with SYSIFCOPT(*ASYNCSIGNAL) is specified on the 
compilation command. 


Table 16. Default Actions for Signal Values 


Value Default Action | Meaning 

SIGABRT 2 Abnormal termination. 

SIGFPE 2 Arithmetic exceptions that are not masked, such 
as overflow, division by zero, and incorrect 
operation. 

SIGILL 2 Detection of an incorrect function image. 

SIGINT 2 Interactive attention. 

SIGSEGV 2 Incorrect access to storage. 

SIGTERM 2 Termination request sent to the program. 

SIGUSR1 2 Intended for use by user applications. 

SIGUSR2 2 Intended for use by user applications. 

SIGALRM 2 A timeout signal that is sent by alarm(). 

SIGHUP 2 A controlling terminal is hung up, or the 
controlling process ended. 

SIGKILL 1 A termination signal that cannot be caught or 
ignored. 

SIGPIPE 3 A write to a pipe that is not being read. 

SIGQUIT 2 A quit signal for a terminal. 

SIGCHLD 3 An ended or stopped child process. SIGCLD is 
an alias name for this signal. 

SIGCONT 5 If stopped, continue. 

SIGSTOP 4 A stop signal that cannot be caught or ignored. 

SIGTSTP 4 A stop signal for a terminal. 

SIGTTIN 4 A background process attempted to read from a 
controlling terminal. 

SIGTTOU 4 A background process attempted to write to a 
controlling terminal. 

SIGIO 3 Completion of input or output. 
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Table 16. Default Actions for Signal Values (continued) 


SIGURG 3 High bandwidth data is available at a socket. 

SIGPOLL 2 Pollable event. 

SIGBUS 2 Specification exception. 

SIGPRE 2 Programming exception. 

SIGSYS 2 Bad system call. 

SIGTRAP 2 Trace or breakpoint trap. 

SIGPROF 2 Profiling timer expired. 

SIGVTALRM 2 Virtual timer expired. 

SIGXCPU 2 Processor time limit exceeded. 

SIGXFSZ 2 File size limit exceeded. 

SIGDANGER 2 System crash is imminent. 

SIGPCANCEL 2 Thread termination signal that cannot be caught 
or ignored. 

Default Actions: 

1 End the process immediately 


End the request. 


Ignore the signal. 


2 
3 
4 Stop the process. 
5 


Continue the process if it is currently stopped. Otherwise, ignore the 


signal. 


Signal to iSeries Exception Mapping 


The following table shows the system exception messages that are mapped to a 
signal. All *ESCAPE exception messages are mapped _to signals. The *STATUS and 
*NOTIFY messages that map to SIGIO as defined in tle onmeegeacd are 


mapped to signals. 


Table 17. Signal to iSeries Exception Mapping 


Signal 
SIGABRT 


Message 
C2M1601 


SIGALL 


C2M1610 (if explicitly raised) 


SIGFPE 


C2M1602, MCH1201 to MCH1204, MCH1206 to MCH1215, MCH1221 to 
MCH1224, MCH1838 to MCH1839 


SIGILL 


SIGINT 


C2M1603, MCH0401, MCH1002, MCH1004, MCH1205, MCH1216 to 
MCH1219, MCH1801 to MCH1802, MCH1807 to MCH1808, MCH1819 to 
MCH1820, MCH1824 to MCH1825, MCH1832, MCH1837, MCH1852, 
MCH1854 to MCH1857, MCH1867, MCH2003 to MCH2004, MCH2202, 
MCH2602, MCH2604, MCH2808, MCH2810 to MCH2811, MCH3201 to 
MCH3203, MCH4201 to MCH4211, MCH4213, MCH4296 to MCH4298, 
MCH4401 to MCH4403, MCH4406 to MCH4408, MCH4421, MCH4427 to 
MCH4428, MCH4801, MCH4804 to MCH4805, MCH5001 to MCH5003, 
MCH5401 to MCH5402, MCH5601, MCH6001 to MCH6002, MCH6201, 
MCH6208, MCH6216, MCH6220, MCH6403, MCH6601 to MCH6602, 
MCH6609 to MCH6612 


C2M1604 
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Table 17. Signal to iSeries Exception Mapping (continued) 


Signal 


Message 


SIGIO 


C2M1609, See [able 14 on page 455) for the exception mappings. 


SIGOTHER 


C2M1611 (if explicitly raised) 


SIGSEGV 


C2M1605, MCH0201, MCH0601 to MCH0606, MCH0801 to MCH0803, 
MCH1001, MCH1003, MCH1005 to MCH1006, MCH1220, MCH1401 to 
MCH1402, MCH1602, MCH1604 to MCH1605, MCH1668, MCH1803 to 
MCH1806, MCH1809 to MCH1811, MCH1813 to MCH1815, MCH1821 to 
MCH1823, MCH1826 to MCH1829, MCH1833, MCH1836, MCH1848, 
MCH1850, MCH1851, MCH1864 to MCH1866, MCH1898, MCH2001 to 
MCH2002, MCH2005 to MCH2006, MCH2201, MCH2203 to MCH2205, 
MCH2401, MCH2601, MCH2603, MCH2605, MCH2801 to MCH2804, 
MCH2806 to MCH2809, MCH3001, MCH3401 to MCH3408, MCH3410, 
MCH3601 to MCH3602, MCH3603 to MCH3604, MCH3802, MCH4001 to 
MCH4002, MCH4010, MCH4212, MCH4404 to MCH4405, MCH4416 to 
MCH4420, MCH4422 to MCH4426, MCH4429 to MCH4437, MCH4601, 
MCH4802 to MCH4803, MCH4806 to MCH4812, MCH5201 to MCH5204, 
MCH5602 to MCH5603, MCH5801 to MCH5804, MCH6203 to MCH6204, 
MCH6206, MCH6217 to MCH6219, MCH6221 to MCH6222, MCH6401 to 
MCH6402, MCH6404, MCH6603 to MCH6608, MCH6801 


SIGTERM 


C2M1606 


SIGUSR1 


C2M1607 


SIGUSR2 


C2M1608 


Cancel Handler Reason Codes 


The following table lists the bits that are set in the reason code. If the activation 

group is to be stopped, then the activation group is stopped bit is also set in the 

reason code. These bits must be correlated to -CNL_MASK_T in 
CNL_Hndlr_Parms_T in <except.h>. Column 2 contains the macro constant 


defined for the cancel reason mask in <except.h>. 


Table 18. Determining Canceled Invocation Reason Codes 


Function 


Bits set in reason code Rationale 


Library routines 


exit 


_EXIT_VERB The definition of exit is normal end of 
processing, and therefore invocations 
canceled by this function is done with a 


reason code of normal. 


abort 


_ABNORMAL_TERM 
_EXIT_VERB 


The definition of abort is abnormal end 
of processing, and therefore invocations 
canceled by this function are done with a 
reason code of abnormal. 


longjmp 


_JUMP The general use of the longjmp() 
function is to return from an exception 
handler, although it may be used in 
non-exception situations as well. It is 
used as part of the “normal” path for a 
program, and therefore any invocations 
canceled because of it are cancelled with 
a reason code of normal. 


Unhandled 
function check 


_ABNORMAL_TERM_ 
UNHANDLED_EXCP 


Not handling an exception which is an 
abnormal situation. 
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Table 18. Determining Canceled Invocation Reason Codes (continued) 


Function Bits set in reason code Rationale 

System APIs 

CEEMRCR _ABNORMAL_TERM This API is only used during exception 

_EXCP_SENT processing. It is typically used to cancel 

invocations where a resume is not 
possible, or at least the behavior would 
be undefined if control was resumed in 
them. Also, these invocations have had a 
chance to handle the exception but did 
not do so. Invocations canceled by this 
API are done with reason code of 
abnormal. 

QMHSNDPM _ABNORMAL_TERM All invocations down to the target 

/QMHRSNEM _EXCP_SENT invocation are canceled without any 

(escape chance of handling the exception. The 

messages) topic contains information on these 


Message Handler 
APIs 


APIs. 


iSeriescommands 


Process end 


_ABNORMAL_TERM 
_PROCESS_TERM 
_AG_TERMINATING 


Any externally initiated shutdown of an 
activation group is considered abnormal. 


RCLACTGRP 


_ABNORMAL_TERM 
_RCLRSC 


The default is abnormal termination. The 
termination could be normal if a 
normal/abnormal flag is added to the 
command. 


Table 19. Common Reason Code for Cancelling Invocations 


Header File Constant 
Bit Description <except.h> 
Bits 0 Reserved 
Bits 1 Invocation canceled due to sending _EXCP_SENT 
exception message 
Bits 2-15 Reserved 
Bit 16 0 - normal end of process 1 - abnormal end | _ABNORMAL_TERM 
of process 
Bit 17 Activation Group is ending. _AG_TERMINATING 
Bit 18 Initiated by Reclaim Activation Group _RCLRSC 
(RCLACTGRP) 
Bit 19 Initiated by the process end. _PROCESS_TERM 
Bit 20 Initiated by an exit() function. _EXIT_VERB 
Bit 21 Initiated by an unhandled function check. _UNHANDLED_EXCP 
Bit 22 Invocation canceled due to a longjmp() _JUMP 
function. 
Bit 23 Invocation canceled due to a jump because | _JUMP_EXCP 
of exception processing. 
Bits 24-31 | Reserved (0) 
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Exception Classes 


In a CL program, you can monitor for a selected group of exceptions, or a single 
exception, based on the exception identifier. The only class2 values the exception 
handler will monitor for are C2 MH_ESCAPE, C2 MH_ STATUS, 

_C2_ MH NOTIPY, and _C2 MH FUNCTION_CHECK. For more information 
about using the #pragma exception handler directive, see the WebSphere 
Development Studio: ILE C/C++ Programmer's Guide. This table defines all the 
exception classes you can specify. 


Table 20. Exception Classes 


Bit position 


Header File Constant in <except.h> 


Exception class 


0 


_C1_BINARY_OVERFLOW 


Binary overflow or divide 
by zero 


_C1_DECIMAL_OVERFLOW 


Decimal overflow or 
divide by zero 


_C1_DECIMAL_DATA_ERROR 


Decimal data error 


_C1_FLOAT_OVERFLOW 


Floating-point overflow or 
divide by zero 


_C1_FLOAT_UNDERFLOW 


Floating-point underflow 
or inexact result 


_C1_INVALID_FLOAT_OPERAND 


Floating-point invalid 
operand or conversion 
error 


C1_OTHER_DATA_ERROR 


Other data error, for 
example edit mask 


_C1_SPECIFICATION_ERROR 


Specification (operand 
alignment) error 


_C1_POINTER_NOT_VALID 


Pointer not set/pointer 
type invalid 


_C1_OBJECT_NOT_FOUND 


Object not found 


_C1_OBJECT_DESTROYED 


Object destroyed 


_C1_ADDRESS_COMP_ERROR 


Address computation 
underflow or overflow 


C1_SPACE_ALLOC_ERROR 


Space not allocated at 
specified offset 


_C1_DOMAIN_OR_STATE_VIOLATION 


Domain/State protection 
violation 


_C1_AUTHORIZATION_VIOLATION 


Authorization violation 


_C1_JAVA_THROWN_CLASS 


Exception thrown for a 
Java class. 


16-28 


_C1_VLIC_RESERVED 


VLIC reserved 


C1_OTHER_MI_EXCEPTION 


Remaining MI-generated 
exceptions (other than 
function check) 


C1_MI_GEN_FC_OR_MC 


MlI-generated function 
check or machine check 


31 


C1_MI_SIGEXP_EXCEPTION 


Message generated via 
Signal Exception 
instruction 
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Table 20. Exception Classes (continued) 


Bit position Header File Constant in <except.h> Exception class 
32-39 n/a reserved 

40 _C2_MH_ESCAPE *ESCAPE 

41 _C2_MH_NOTIFY *NOTIFY 

42 _C2_MH_STATUS *STATUS 

43, _C2_ MH_FUNCTION_CHECK function check 
44-63 n/a reserved 


Data Type Compatibility 


Each high-level language has different data types. When you want to pass data 
between programs that are written in different languages, you must be aware of 
these differences. 


Some data types in the ILE C programming language have no direct equivalent in 
other languages. However, you can simulate data types in other languages that use 
ILE C data types. 

The following table shows the ILE C data type compatibility with ILE RPG. 


Table 21. ILE C Data Type Compatibility with ILE RPG 


ILE C declaration | ILE RPG D spec, columns 33 


in prototype to 39 Length |Comments 

char[n] nA n An array of characters 

char * where n=1 to 32766. 

char 1A 1 An Indicator that is a 
variable starting with *IN. 

char[n] ns 0 n A zoned decimal. 

char[2n] nG 2n A graphic added. 

char[2n+2] Not supported. 2n+2 A graphic data type. 

_Packed struct Not supported. n+2 A variable length field 

{short i; char[n]} where i is the intended 


length and n is the 
maximum length. 


char[n] D 8, 10 A date field. 

char[n] T 8 A time field. 

char[n] 7 26 A timestamp field. 

short int 51 0 2 An integer field. 

short unsigned 5U 0 2, An unsigned integer field. 
int 

int 101 0 4 An integer field. 
unsigned int 10U 0 4 An unsigned integer field 
long int 101 0 4 An integer field. 

long unsigned int 10U 0 4 An unsigned integer field. 
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Table 21. ILE C Data Type Compatibility with ILE RPG (continued) 


ILE C declaration 


ILE RPG D spec, columns 33 


with keyword PROCPTR 


in prototype to 39 Length |Comments 

struct {unsigned | Not supported. 4 A 4-byte unsigned integer, 

int : n}x; a bitfield. 

float Not supported. 4 A 4byte floating point. 

double Not supported. 8 An 8-byte double. 

long double Not supported. 8 An 8-byte long double. 

enum Not supported. 1,2,4 Enumeration. 

- ie 16 A pointer. 

decimal(n,p) nP p n/2+1 A packed decimal. n must 
be less than or equal to 30. 

union.element <type> with keyword element | An element of a union. 

OVERLAY (longest field) length 

data_type[n] <type> with keyword DIM(n) | 16 An array to which C 
passes a pointer. 

struct data structure n A structure. Use the 
_Packed qualifier on the 
struct. 

pointer to ce 16 A 16-byte pointer. 

function 


The following table shows the ILE C data type compatibility with ILE COBOL. 
Table 22. ILE C Data Type Compatibility with ILE COBOL 


ILE C declaration ILE COBOL LINKAGE 
in prototype SECTION Length Comments 
char[n] PIC X(n). n An array of characters where 
char * n=1 to 3,000,000 
char PIC 1 INDIC .. 1 An indicator. 
char[n] PIC S9(n) DISPLAY n A zoned decimal. 
wchar_t[n] PIC G(n) 2n A graphic data type. 
_Packed struct 05 VL-FIELD. n+2 A variable length field where i 
{short i; char[n]} 10 i PIC S94) is the intended length and n is 
COMP-4. the maximum length. 
10 data PIC X(n). 
char[n] PIC X(n). 6 A date field. 
char[n] PIC X(n). 5 A day field. 
char PIC X. 1 A day-of-week field. 
char[n] PIC X(n). 8 A time field. 
char[n] PIC X(n). 26 A time stamp field. 
short int PIC S9(4) COMP-4. 2 A 2-byte signed integer with a 
range of -9999 to +9999. 
short int PIC S9(4) BINARY. 2 A 2-byte signed integer with a 
range of -9999 to +9999. 
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Table 22. ILE C Data Type Compatibility with ILE COBOL (continued) 


ILE C declaration 


ILE COBOL LINKAGE 


in prototype SECTION Length Comments 

int PIC S9(9) COMP-4. 4 A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

int PIC S9(9) BINARY. + A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

int USAGE IS INDEX 4 A 4byte integer. 

long int PIC S9(9) COMP-4. A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

long int PIC S9(9) BINARY. 4 A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

struct {unsigned int | PIC 9(9) COMP-4. 4 Bitfields can be manipulated 

> n}x; PIC X(A4). using hex literals. 

float Not supported. 4 A 4byte floating point. 

double Not supported. 8 An 8-byte double. 

long double Not supported. 8 An 8-byte long double. 

enum Not supported. 1, 2,4 Enumeration. 

: USAGE IS POINTER 16 A pointer. 

decimal(n,p) PIC S9(n-p)V9(p) n/2+1 A packed decimal. 

COMP-3 
decimal(n,p) PIC S9(n-p) 9(p) n/2+1 A packed decimal. 
PACKED-DECIMAL 
union.element REDEFINES element An element of a union. 
length 

data_type[n] OCCURS 16 An array to which C passes a 
pointer. 

struct 01 record n A structure. Use the _Packed 

05 field1 qualifier on the struct. 

05 field2 Structures passed should be 
passed as a pointer to the 
structure if you want to 
change the contents of the 
structure. 

pointer to function |PROCEDURE-POINTER | 16 A 16 byte pointer to a 
procedure. 

Not supported. PIC S9(18) COMP-4. 8 An 8 byte integer. 

Not supported. PIC S9(18) BINARY. 8 An 8 byte integer. 
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The following table shows the ILE C data type compatibility with ILE CL. 


Table 23. ILE C Data Type Compatibility with ILE CL 


ILE C declaration in 


prototype CL Length Comments 

char[n] *CHAR LEN(&N) n An array of characters where 

char * n=1 to 32766. A null-terminated 
string. For example, CHGVAR 
&V1 VALUE (&V *TCAT X’00’) 
where &V1 is one byte bigger 
than &V. 

char *LGL 1 Holds ’1’ or ’0’. 

_Packed struct {short | Not supported. n+2 A variable length field where i 

i; char[n]} is the intended length and n is 
the maximum length. 

integer types Not supported. 1,2,4 A 1-, 2-, or 4- byte signed or 
unsigned integer. 

float constants CL constants only. 4 A 4- or 8- byte floating point. 

decimal(n,p) *DEC n/2+1 A packed decimal. The limit of 
nis 15 and p is 9. 

union.element Not supported. element An element of a union. 

length 

struct Not supported. n A structure. Use the _Packed 
qualifier on the struct. 

pointer to function Not supported. 16 A 16-byte pointer. 


The following table shows the ILE C data type compatibility with OPM RPG/400°. 
Table 24. ILE C Data Type Compatibility with OPM RPG/400 


ILE C declaration 


OPM RPG/400 I spec, 
DS subfield columns 


in prototype spec Length Comments 

char[n] 110 n An array of characters where 

char * n=1 to 32766. 

char *INxxxx 1 An Indicator that is a variable 
starting with *IN. 

char[n] 1 nd (d>=0) n A zoned decimal. The limit of 
n is 30. 

char[2n+2] Not supported. 2n+2 A graphic data type. 

_Packed struct Not supported. n+2 A variable length field where i 

{short i; char[n]} is the intended length and n is 
the maximum length. 

char[n] Not supported. 6, 8, 10 A date field. 

char[n] Not supported. 8 A time field. 

char[n] Not supported. 26 A time stamp field. 

short int B 1 20 2 A 2-byte signed integer with a 
range of -9999 to +9999. 

int B 1 40 4 A 4-byte signed integer with a 


range of -999999999 to 
+999999999. 
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Table 24. ILE C Data Type Compatibility with OPM RPG/400 (continued) 


ILE C declaration 


OPM RPG/400 I spec, 
DS subfield columns 


in prototype spec Length Comments 

long int B 1 40 4 A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

struct {unsigned int | Not supported. 4 A 4-byte unsigned integer, a 

:n}x; bitfield. 

float Not supported. 4 A 4byte floating point. 

double Not supported. 8 An 8-byte double. 

long double Not supported. 8 An 8-byte long double. 

enum Not supported. 1, 2,4 Enumeration. 

‘i Not supported. 16 A pointer. 

decimal(n,p) P 1 n/2+1d n/2+1 A packed decimal. n must be 
less than or equal to 30. 

union.element data structure subfield element An element of a union. 

length 

data_type[n] E-SPEC array 16 An array to which C passes a 
pointer. 

struct data structure n A structure. Use the _Packed 
qualifier on the struct. 

pointer to function | Not supported. 16 A 16 byte pointer. 


The following table 
COBOL /400™. 


Table 25. ILE C Data 


shows the ILE C data type compatibility with OPM 


Type Compatibility with OPM COBOL/400 


ILE C declaration |OPM COBOL 

in prototype LINKAGE SECTION Length Comments 

char[n] PIC X(n). n An array of characters where 

char * n=1 to 3,000,000 

char PIC 1 INDIC .. 1 An indicator. 

char[n] PIC S9(n) USAGE IS n A zoned decimal. The limit of 

DISPLAY nis 18. 
_Packed struct 05 VL-FIELD. n+2 A variable length field where i 
{short i; char[n]} 10 i PIC S9(4) is the intended length and n is 
COMP-4. the maximum length. 
10 data PIC X(n). 

char[n] PIC X(n). 6, 8, 10 A date field. 

char[n] PIC X(n). 8 A time field. 

char[n] PIC X(n). 26 A time stamp field. 

short int PIC S9(4) COMP-4. 2 A 2 byte signed integer with a 
range of -9999 to +9999. 

int PIC S9(9) COMP-4. + A 4-byte signed integer with a 
range of -999999999 to 
+999999999. 

long int PIC S9(9) COMP-4. 4 A 4byte signed integer with a 


range of -999999999 to 
+999999999. 
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Table 25. ILE C Data Type Compatibility with OPM COBOL/400 (continued) 


ILE C declaration |OPM COBOL 

in prototype LINKAGE SECTION Length Comments 

struct {unsigned int | PIC 9(9) COMP-4. 4 Bitfields can be manipulated 

:n}x; PIC X(4). using hex literals. 

float Not supported. 4 A 4byte floating point. 

double Not supported. 8 An 8-byte double. 

long double Not supported. 8 An 8-byte long double. 

enum Not supported. 1, 2,4 Enumeration. 

* USAGE IS POINTER 16 A pointer. 

decimal(n,p) PIC S9(n-p)V9(p) n/2+1 A packed decimal. The limits 

COMP-3 of n and p are 18. 
union.element REDEFINES element An element of a union. 
length 

data_type[n] OCCURS 16 An array to which C passes a 
pointer. 

struct 01 record n A structure. Use the _Packed 
qualifier on the struct. 
Structures passed should be 
passed as a pointer to the 
structure if you want to 
change the contents of the 
structure. 

pointer to function | Not supported. 16 A 16-byte pointer. 

Not supported. PIC $9(18) COMP-4. 8 An 8 byte integer. 


The following table shows the ILE C data type compatibility with CL. 


Table 26. ILE C Data Type Compatibility with CL 


ILE C declaration in 


prototype CL Length Comments 

char[n] *CHAR LEN(&N) n An array of characters where 

char * n=1 to 32766. A null terminated 
string. For example, CHGVAR 
&V1 VALUE (&V *TCAT X’00’) 
where &V1 is one byte bigger 
than &V. The limit of n is 9999. 

char *LGL 1 Holds ‘1’ or ’0’. 

_Packed struct {short | Not supported. n+2 A variable length field where i 

i; char[n]} is the intended length and n is 
the maximum length. 

integer types Not supported. 1, 2,4 A 1-, 2- or 4- byte signed or 
unsigned integer. 

float constants CL constants only. 4 A4- or 8- byte floating point. 

decimal(n,p) *DEC n/2+1 A packed decimal. The limit of 
nis 15 and p is 9. 

union.element Not supported. element An element of a union. 

length 
struct Not supported. n A structure. Use the _Packed 


qualifier on the struct. 
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Table 26. ILE C Data Type Compatibility with CL (continued) 


ILE C declaration in 
prototype 


pointer to function 


CL 
Not supported. 


Length Comments 


16 A 16-byte pointer. 


The following table shows how arguments are passed from a command line CL 
call to an ILE C program. 


Table 27. Arguments Passed From a Command Line CL Call to an ILE C Program 


Command Line Argument | Argv Array ILE C Arguments 
argv[0] "LIB/PGMNAME" 
argv[1..255] normal parameters 

123.4’ argv[1] "123.4" 

123.4 argv[2] 0000000123.40000D 

Hi’ argv[3] "Hi" 

Lo argvi4] "LO" 


A CL character array (string) will not be NULL-ended when passed to an ILE C 
program. A C program that will receive such arguments from a CL program 
should not expect the strings to be NULL-ended. You can use the QCMDEXC to 
ensure that all the arguments will be NULL-ended. 


The following table shows how CL constants are passed from a compiled CL 
program to an ILE C program. 


Table 28. CL Constants Passed from a Compiled CL Program to an ILE C Program 


Compile CL Program 


Argument Argv Array ILE C Arguments 
argv[0] "LIB/PGMNAME" 
argv[1..255] normal parameters 

123.4’ argv[1] "123.4" 

123.4 argv[2] 0000000123.40000D 

Hi’ argv[3] "Hi" 

Lo argvl4] "LO" 


A command processing program (CPP) passes CL constants as defined in [able 29. 
You define an ILE C program as a command processing program when you create 
your own CL command with the Create Command (CRTCMD) command to call 


the ILE C program. 


The following table shows how CL variables are passed from a compiled CL 
program to an ILE C program. All arguments are passed by reference from CL to 


C. 


Table 29. CL Variables Passed from a Compiled CL Program to an ILE C Program 


CL Variables 


ILE C Arguments 


VALUE('123.4’) 


DCL VAR(&v) TYPE(*CHAR) LEN(10) 


123.4 
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Table 29. CL Variables Passed from a Compiled CL Program to an ILE C 
Program (continued) 


CL Variables 


ILE C Arguments 


VALUE('1’) 


DCL VAR(&d) TYPE(*DEC) LEN(10) 0000000123.40000D 
VALUE(123.4) 

DCL VAR(&h) TYPE(*CHAR) LEN(10) Hi 

VALUE(’Hi’) 

DCL VAR(&i) TYPE(*CHAR) LEN(10) LO 

VALUE(Lo) 

DCL VAR(&j) TYPE(*LGL) LEN(1) 1 


CL variables and numeric constants are not passed to an ILE C program with 
null-ended strings. Character constants and logical literals are passed as null-ended 
strings, but are not padded with blanks. Numeric constraints such as packed 


decimals are passed as 15,5 (8 bytes). 


Run-time Character Set 


Each EBCDIC CCSID consists of two character types: invariant characters and 
variant characters. 


The following table identifies the hexadecimal representation of the invariant 
characters in the C character set. 


Table 30. Invariant Characters 


; < ( + & . ) ; 
Ox4b Ox4c Ox4d Ox4e 0x50 Ox5c Ox5d Ox5e 
= ' , % Ley > ? 5 
0x60 Ox6a O0x6b Ox6c Ox6d Ox6e Ox6f Ox7a 
@ ‘ = 7 a-i jr S-Z A-I 
Ox7c Ox7d Ox7e Ox7f Ox81 - Ox91 - Oxa2 - Oxcl - 
0x89 0x99 Oxa9 Oxc9 
J-R S-Z 0-9 ’Nae ‘\b’ ‘\t! oy! ‘\f’ 
Oxd1 - Oxe2 - Oxf0 - Ox2f 0x16 0x05 0x0b 0x0c 
Oxd9 Oxe9 Oxf9 
¥ \r’ , \n’ ar 
Ox0d 0x15 0x40 


The following table identifies the hexadecimal representation of the variant 
characters in the C character set for the most commonly used CCSIDs. 


Table 31. Variant Characters in Different CCSIDs 


CcC- 
SID | | ! 


[ ] ‘ { } 


/ 


¢ $ 


037 | Ox4f | Ox5a 


0x79 


Oxba| Oxbb] 0xb0} Oxc0 | Oxd0 


0x61 


Ox4a | 0x5b 


256 | Oxbb] 0x4f 


0x79 


Ox4a | Ox5a | Ox5f | OxcO | Oxd0 


0x61 


Oxb0| 0x5b 


273 | Oxbb] Ox4f 


0x79 


0x63 | Oxfe | Ox5f | 0x43 | Oxde 


0x61 


Oxb0| 0x5b 


277 | Oxbb) Ox4f 


0x79 


Ox9e | Ox9F | Ox5f | Ox9c | 0x47 


Ox61 


Oxb0 | 0x67 


278 | Oxbb] Ox4f 


0x51 


Oxb5| Ox9f | Ox5£ | 0x43 | 0x47 


0x61 


Oxb2| 0x67 


280 | Oxbb] 0x4f 


Oxdd 


0x90 | 0x51 | Ox5f | 0x44} 0x45 


0x61 


Oxb0| 0x5b 
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Table 31. Variant Characters in Different CCSIDs (continued) 


cc 
SID]! |! J> IN | f# |r Jk Ji to Te yb |r Je I$ 


284 | Ox4f | Oxbb] Ox5f | OxeO | 0x79 | 0x69 | Oxbd| 0x4a | Ox5a | Oxba} OxcO | Oxd0) 0x61 | Oxb0 | Ox5b 
285. | Ox4f | Ox5a | Ox5f | Oxe0 | 0x79 | 0x7b | Oxbc | Oxb1} Oxbb} Oxba]| OxcO | Oxd0} 0x61 | Oxb0 | Ox4a 
297 | Oxbb] Ox4f | Oxba| 0x48 | Oxa0 | Oxb1} Oxbd] 0x90 | 0x65 | Ox5f | 0x51 | 0x54 | 0x61} Oxb0} 0x5b 
500 | Oxbb} 0x4f | Oxba| Oxe0 | 0x79 | 0x7b | Oxal | Ox4a | Ox5a | Ox5f | Oxc0 | Oxd0} 0x61 | Oxb0} 0x5b 


See the Globalizationl topic for more information on coding variant characters in 
the other IBM CCSIDs. 


Asynchronous Signal Model 


The Asynchronous Signal Model (ASM) is used when the 
SYSIFCOPT(#*ASYNCSIGNAL) option is specified on the the compilation. It is 
inteded for campatibility with applications ported from the UNIX operating 
system. In the ASM model, the signal() and raise() functions are implemented 
using the OS/400 Signal APIs described in the API topic under the Programming 
heading in the Information Center. 


OS/400 exceptions sent to an ASM program are converted to asynchronous signals. 
The exceptions are processed by an asynchronous signal handler 


Modules compiled to use the ASM can be intermixed with modules using the 
Original Signal Model (OSM) in the same processes, programs, and service 
programs. This is true even when SYSIFCOPT(*ASYNCSIGNAL) is not specified 
on the compilation command for programs compiled with the OSM. There are 
several differences between the two signal models: 


* The OSM is based on exceptions, while the ASM is based on asynchronous 
signals. 


* Under the OSM, the signal vector and signal mask are scoped to the activation 
group. Under ASM, there is one signal vector per process and one signal mask 
per thread. Both types of signal vectors and signal masks are maintained during 
compilation. 


* The same asynchronous signal vector and signal masks are operated on by all 
ASM modules in a thread, regardless of the activation group the signal vector 
and signal masks belong to. You should save and restore the state of the signal 
vector and signal masks to ensure that they are not changed by any ASM 
modules. The OSM does not use the asynchronous signal vector and signal 
masks. 


* Signals raised by OSM programs will be sent as exceptions. Under the OSM, the 
exceptions are received and handled by the _C_exception_router function, 
which directly invokes the OSM signal handler of the the user. 


Asynchronous signals are not mapped to exceptions, and are not handled by 
signal handlers registered under the OSM. Under the ASM, the exceptions are 
received and handled by the _C_async_exception_router function, which maps 
the exception to an asynchronous signal, and uses the SNDSIG MI instruction to 
raise an asynchronous signal. An ASM signal handler receives control from the 
OS/400 asynchonous signal component. 


When an OSM program raises a signal, the generated exception percolates up 
the invocation stack until it finds an exception monitor. If the prior invocation is 
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an OSM function, the _C_exception_router catches the exception and performs 
the OSM signal action. The ASM signal handler does not receive the signal. 


If the prior invocation is an ASM function, the _C_async_exception_router 
handles the exception, maps to an asynchronous signal, and raises it using the 
MI SNDSIG instruction. The handling of the asynchronous signal then depends 
on the asynchronous signal vector and mask state of the thread, as defined in 
the OS/400 Signal Management topic. 


If the OSM program raising the signal is running in the same activation group 
with the ASM program, the exception will be mapped to an asynchronous signal 
using the mapping described previously. The signal ID is preserved when the 
exception is mapped to a signal. So, signal handlers registered with the 
asynchronous signal model will be able to receive signals generated under the 
original signal model. Use this approach to integrate two programs using 
different signal models. 


If a program or service program using the OSM is running a different activation 
group, any signal that is unmonitored in that activation group will cause the 
termination of that program and activation group. The unmonitored signal is 
then percolated to the calling program as a CEE9901 exception. The CEE9901 
exception is mapped to a SIGSEGV asynchronous signal. 


Note: This approach is not recommended. 


Under the ASM, the C functionsraise() and signal() are integrated with the 
system signal functions, such as kil1() and sigaction(). These two sets of APIs 
can be used interchangeably. This cannot be done under the OSM. 


A user-specified exception monitor established with #pragma_exception_handler 
has precedent over the compiler-generated monitor, which invokes 
_C_async_exception_router. This precedence enables you to bypass the 
asynchronous signal generating exception monitor in some situations. 


The _GetExcData() function is not available under the ASM to retrieve the 
exception ID associated with the signal. If an extended signal handler is 
established using the sigaction() function, however, it can access the exception 
information from the signal-specific data structure. For more information, see 
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Appendix A. Library Functions and Extensions 


This chapter summarizes all the standard C library functions and the ILE Clibrary 


extensions. 


Standard C Library Functions Table, By Name 


This table briefly describes the C library functions, listed in alphabetical order. This 
table provides the include file name and the function prototype for each function. 


Table 32. Standard C Library Functions 


System 
Function Include File | Function Prototype Description 
abort stdlib.h void abort(void); Stops a program abnormally. 
abs stdlib.h int abs(int 1); Calculates the absolute value 
of an integer argument n. 
acos math.h double acos(double x); | Calculates the arc cosine of x. 
asctime time.h char *asctime(const Converts the time that is 
struct tm *time); stored as a structure to a 
character string. 
asctime_r time.h char *asctime_r (const Converts tm that is stored as a 
struct tm *tm, char structure to a character string. 
*buf); (Restartable version of 
asctime.) 
asin math.h double asin(double x); | Calculates the arc sine of x. 
assert assert.h void assert(int Prints a diagnostic message 
expression); and ends the program if the 
expression is false. 
atan math.h double atan(double x); | Calculates the arc tangent of x. 
atan2 math.h double atan2(double y, | Calculates the arc tangent of 
double x); y/x. 
atexit stdlib.h int atexit(void Registers a function to be 
(*func)(void)); called at normal termination. 
atof stdlib.h double atof(const char | Converts string to a 
*string); double-precision floating-point 
value. 
atoi stdlib.h int atoi(const char Converts string to an integer. 
*string); 
atol stdlib.h long int atol(const char | Converts string to a long 
*string); integer. 
bsearch stdlib.h void *bsearch(const void | Performs a binary search on 
*key, const void *base, an array of num elements, 
size_t num, size_t size, each of size bytes. The array 
int (*compare) (const must be sorted in ascending 
void *element1, const order by the function pointed 
void *element2)); to by compare. 
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Table 32. Standard C Library Functions (continued) 


System 
Function Include File | Function Prototype Description 
btowc stdio.h wint_t btowc(int c); Determines whether c 
wchar.h constitues a valid multibyte 
character in the initial shift 
state. 
calloc stdlib.h void *calloc(size_t num, | Reserves storage space for an 
size_t size); array of num elements, each of 
size size, and initializes the 
values of all elements to 0. 
catclose® nl_types.h | int catclose (nl_catd Closes a previously opened 
catd); message catalog. 
catgets® nl_types.h | char *catgets(nl_catd Retrieves a message from an 
catd, int set_id, int open message catalog. 
msg_id, const char *s); 
catopen® nl_types.h |nl_catd catopen (const | Opens a message catalog, 
char *name, int oflag); | which must be done before a 
message can be retrieved. 
ceil math.h double ceil(double x); Calculates the double value 
representing the smallest 
integer that is greater than or 
equal to x. 
clearerr stdio.h void clearerr(FILE Resets the error indicators and 
*stream); the end-of-file indicator for 
stream. 
clock time.h clock_t clock(void); Returns the processor time 
that has elapsed since the job 
was started. 
cos math.h double cos(double x); Calculates the cosine of x. 
cosh math.h double cosh(double x); | Calculates the hyperbolic 
cosine of x. 
ctime time.h char *ctime(const time_t | Converts time to a character 
*time); string. 
ctime_r time.h char *ctime_r(const Converts timer to a character 
time_t “timer, char *buf); | string. (Restartable version of 
ctime.) 
difftime time.h double difftime(time_t Computes the difference 
time2, time_t time1); between fime2 and time1. 
div stdlib.h div_t div(int numerator, | Calculates the quotient and 
int denominator); remainder of the division of 
numerator by denominator. 
erf math.h double erf(double x); Calculates the error function 
of x. 
erfc math.h double erfc(double x); Calculates the error function 
for large values of x. 
exit stdlib.h void exit(int status); Ends a program normally. 
exp math.h double exp(double x); Calculates the exponential 
function of a floating-point 
argument x. 
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fabs math.h double fabs(double x); | Calculates the absolute value 
of a floating-point argument x. 
fclose stdio.h int fclose(FILE *stream); | Closes the specified stream. 
fdopen? stdio.h FILE *fdopen(int handle, | Associates an input or output 
const char “type); stream with the file identified 
by handle. 
feof stdio.h int feof(FILE *stream); Tests whether the end-of-file 
flag is set for a given stream. 
ferror stdio.h int ferror(FILE *stream); | Tests for an error indicator in 
reading from or writing to 
stream. 
fflush? stdio.h int fflush(FILE *stream); | Writes the contents of the 
buffer associated with the 
output stream. 
fgetc! stdio.h int fgetc(FILE *stream); | Reads a single unsigned 
character from the input 
stream. 
fgetpos' stdio.h int fgetpos(FILE *stream, | Stores the current position of 
fpos_t *pos); the file pointer associated with 
stream into the object pointed 
to by pos. 
fgets! stdio.h char *fgets(char “string, | Reads a string from the input 
int n, FILE *stream); stream. 
fgetwe® stdio.h wint_t fgetwc(FILE Reads the next multibyte 
wchar.h *stream); character from the input 
stream pointed to by stream. 
fgetws° stdio.h wchar_t Reads wide characters from 
wchar.h *feetws(wchar_t *wes, the stream into the array 
int n, FILE *stream); pointed to by wes. 
fileno® stdio.h int fileno(FILE *stream); | Determines the file handle 
currently associated with 
stream. 
floor math.h double floor(double x); | Calculates the floating-point 
value representing the largest 
integer less than or equal to x. 
fmod math.h double fmod(double x, | Calculates the floating-point 
double y); remainder of x/y. 
fopen stdio.h FILE *fopen(const char | Opens the specified file. 
“filename, const char 
*mode); 
fprintf stdio.h int fprintf(FILE *stream, | Formats and prints characters 
const char *format-string, | and values to the output 
arg-list); stream. 
fputc! stdio.h int fputc(int c, FILE Prints a character to the 
*stream); output stream. 
fputs' stdio.h int fputs(const char Copies a string to the output 


*string, FILE *stream); 


stream. 
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fputwc® stdio.h wint_t fputwc(wchar_t | Converts the wide character 
wchar.h we, FILE *stream); we to a multibyte character 
and writes it to the output 
stream pointed to by stream at 
the current position. 
fputws® stdio.h int fputws(const Converts the wide-character 
wchar.h wchar_t *wces, FILE string wes to a 
*stream); multibyte-character string and 
writes it to stream asa 
multibyte character string. 
fread stdio.h size_t fread(void *buffer, | Reads up to count items of size 
size_t size, size_t count, | length from the input stream, 
FILE *stream); and stores them in buffer. 
free stdlib.h void free(void *ptr); Frees a block of storage. 
freopen stdio.h FILE *freopen(const char | Closes stream, and reassigns it 
*filename, const char to the file specified. 
*mode, FILE *stream); 
frexp math.h double frexp(double x, | Separates a floating-point 
int *expptr); number into its mantissa and 
exponent. 
fscanf stdio.h int fscanf(FILE *stream, | Reads data from stream into 
const char *format-string, | locations given by arg-list. 
arg-list); 
fseek! stdio.h int fseek(FILE *stream, Changes the current file 
long int offset, int origin); | position associated with stream 
to a new location. 
fsetpos! stdio.h int fsetpos(FILE “stream, | Moves the current file position 
const fpos_t *pos); to a new location determined 
by pos. 
ftell’ stdio.h long int ftell(FILE Gets the current position of 
*stream); the file pointer. 
fwide® stdio.h int fwide(FILE “stream, | Determines the orientation of 
wchar.h int mode); the stream pointed to by 
stream. 
fwprintf® stdio.h int fwprintf(FILE Writes output to the stream 
wchar.h *stream, const wchar_t pointed to by stream. 
*format, arg-list); 
fwrite stdio.h size_t fwrite(const void | Writes up to count items of 
“buffer, size_t size,size_t | size length from buffer to 
count, FILE *stream); stream. 
fwscanf° stdio.h int fwscanf(FILE “stream, | Reads input from the stream 
wchar.h const wchar_t *format, pointed to by stream. 
arg-list) 
gamma math.h double gamma(double | Computes the Gamma 
Xx); Function 
getc! stdio.h int getc(FILE “stream); Reads a single character from 
the input stream. 
getchar! stdio.h int getchar(void); Reads a single character from 
stdin. 
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getenv stdlib.h char *getenv(const char | Searches environment 
*varname); variables for varname. 
ets stdio. char *gets(char *buffer); eads a string from stdin, an 
get tdio.h har *gets(char *buffer); | Read: tring f tdin, and 
stores it in buffer. 
getwc® stdio.h wint_t getwc(FILE Reads the next multibyte 
wchar.h *stream); character from stream, converts 
it to a wide character and 
advances the associated file 
position indicator for stream. 
etwchar wchar. win etwchar(void); eads the next multibyte 
getwchar® har.h int_t getwchar(void); | Reads th t multibyt 
character from stdin, converts 
it to a wide character, and 
advances the associated file 
position indicator for stdin. 
gmtime time.h struct tm *gmtime(const | Converts a time value to a 
time_t *time); structure of type tm. 
gmtime_r time.h struct tm *gmtime_r Converts a timer value to a 
(const time_t *timer, structure of type tm. 
struct tm *result); (Restartable version of 
gmtime.) 
hypot math.h double hypot(double Calculates the hypotenuse of a 
side1, double side2); right-angled triangle with 
sides of length side1 and side2. 
isalnum ctype.h int isalnum(int c); Tests if c is alphanumeric. 
isalpha ctype.h int isalpha(int c); Tests if c is alphabetic. 
isascii ctype.h int isascii(int c); Tests if c is within the 7-bit 
US-ASCII range. 
iscntrl ctype.h int iscntrl(int c); Tests if c is a control character. 
isdigit ctype.h int isdigit(int c); Tests if c is a decimal digit. 
isgraph ctype.h int isgraph(int c); Tests if c is a printable 
character excluding the space. 
islower ctype.h int islower(int c); Tests if c is a lowercase letter. 
isprint ctype.h int isprint(int c); Tests if c is a printable 
character including the space. 
ispunct ctype.h int ispunct(int c); Tests if c is a punctuation 
character. 
isspace ctype.h int isspace(int c); Tests if c is a whitespace 
character. 
isupper ctype.h int isupper(int c); Tests if c is an uppercase 
letter. 
iswalnum* wctype.h int iswalnum (wint_t Checks for any alphanumeric 
we); wide character. 
iswalpha wctype. int iswalpha (win ecks for any alphabetic 
i Ipha* type.h int i Ipha (wint_t Checks f y alphabeti 
we); wide character. 
iswentrl* wctype.h int iswentrl (wint_t wc); | Tests for any control wide 


character. 
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iswctype* wctype.h int iswctype(wint_t wc, | Determines whether or not the 
wctype_t wce_prop); wide character wc has the 
property wc_prop. 
iswdigit* wctype.h int iswdigit (wint_t wc); | Checks for any decimal-digit 
wide character. 
iswgraph* wctype.h int iswgraph (wint_t Checks for any printing wide 
we); character except for the 
wide-character space. 
iswlower* wctype.h int iswlower (wint_t Checks for any lowercase 
we); wide character. 
iswprint* wctype.h int iswprint (wint_t wc); | Checks for any printing wide 
character. 
iswpunct* wetype.h int iswpunct (wint_t Test for a wide 
we); non-alphanumeric, non-space 
character. 
iswspace* wctype.h int iswspace (wint_t Checks for any wide character 
we); that corresponds to an 
implementation-defined set of 
wide characters for which 
iswalnum is false. 
iswupper* wctype.h int iswupper (wint_t Checks for any uppercase 
we); wide character. 
iswxdigit* wctype.h int iswxdigit (wint_t Checks for any hexadecimal 
we); digit character. 
isxdigit* wctype.h int isxdigit(int c); Tests if c is a hexadecimal 
digit. 
jo math.h double j0(double x); Calculates the Bessel function 
value of the first kind of order 
0. 
jl math.h double j1(double x); Calculates the Bessel function 
value of the first kind of order 
1; 
jn math.h double jn(int n, double | Calculates the Bessel function 
x); value of the first kind of order 
n. 
labs stdlib.h long int labs(long int 1); | Calculates the absolute value 
of n. 
Idexp math.h double Idexp(double x, | Returns the value of x 
int exp); multiplied by (2 to the power 
of exp). 
Idiv stdlib.h Idiv_t Ildiv(long int Calculates the quotient and 
numerator, long int remainder of 
denominator); numerator / denominator. 
localeconv locale.h struct lconv Formats numeric quantities in 
*localeconv(void); struct lconv according to the 
current locale. 
localtime time.h struct tm Converts timeval to a structure 
*“localtime(const time_t | of type tm. 
*timeval); 
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localtime_r time.h struct tm *localtime_r Converts a timer value to a 
(const time_t *timeval, | structure of type tm. 
struct tm *result); (Restartable version of 
localtime.) 
log math.h double log(double x); Calculates the natural 
logarithm of x. 
log10 math.h double log10(double x); | Calculates the base 10 
logarithm of x. 
longjmp setimp.h void longjmp(jmp_buf | Restores a stack environment 
env, int value); previously set in env by the 
setimp function. 
malloc stdlib.h void *malloc(size_t size); | Reserves a block of storage. 
mblen stdlib.h int mblen(const char Determines the length of a 
“string, size_t n); multibyte character string. 
mbrlen* wchar.h int mbrlen (const char Determines the length of a 
*s size_t n, mbstate_t multibyte character. 
*ps); (Restartable version of mblen.) 
mbrtowc* wchar.h int mbrtowc (wchar_t Convert a multibyte character 
*pwc, const char *s, to a wide character 
size_t n, mbstate_t *ps); | (Restartable version of 
mbtowc.) 
mbsinit* wchar.h int mbsinit (const Test state object “ps for initial 
mbstate_t *ps); state. 
mbsrtowcs* wchar.h size_t mbsrtowc Convert multibyte string to a 
(wchar_t *dst, const char | wide character string. 
**src, size_t len, (Restartable version of 
mbstate_t *ps); mbstowcs.) 
mbstowcs stdlib.h size_t Converts the multibyte 
mbstowcs(wchar_t *pwe, | characters in string to their 
const char *string, size_t | corresponding wchar_t codes, 
n); and stores not more than 1 
codes in pwe. 
mbtowc stdlib.h int mbtowc(wchar_t Stores the wchar_t code 
*pwce, const char *string, | corresponding to the first n 
size_t n); bytes of multibyte character 
string into the wchar_t 
character pwe. 
memchr string.h void *memchr(const Searches the first count bytes 
void *buf, int c, size_t of buf for the first occurrence 
count); of c converted to an unsigned 
character. 
memcmp string.h int memcmp(const void | Compares up to count bytes of 
*bufl, const void *buf2, | bufl and buf2. 
size_t count); 
memcpy string.h void *memcpy(void Copies count bytes of src to 
*dest, const void *src, dest. 
size_t count); 
memmove string.h void *memmove(void Copies count bytes of src to 


*dest, const void *src, 
size_t count); 


dest. Allows copying between 
objects that overlap. 
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memset string.h void *memset(void *dest, | Sets count bytes of dest to a 
int c, size_t count); value c. 
mktime time.h time_t mktime(struct tm | Converts local time into 
*time); calendar time. 
modf math.h double modf(double x, | Breaks down the 
double *intptr); floating-point value x into 
fractional and integral parts. 
nl_langinfo* langinfo.h | char Retrieve from the current 
*nl_langinfo(nl_item locale the string that describes 
item); the requested information 
specified by item. 
perror stdio.h void perror(const char | Prints an error message to 
*string); stderr. 
pow math.h double pow(double x, Calculates the value x to the 
double y); power y. 
printf stdio.h int printf(const char Formats and prints characters 
*format-string, arg-list); and values to stdout. 
putc! stdio.h int putc(int c, FILE Prints c to the output stream. 
*stream); 
putchar! stdio.h int putchar(int c); Prints c to stdout. 
putenv stdlib.h int *putenv(const char | Sets the value of an 
*varname); environment variable by 
altering an existing variable or 
creating a new one. 
puts stdio.h int puts(const char Prints a string to stdout. 
*string); 
putwc® stdio.h wint_t Converts the wide character 
wchar.h putwchar(wchar_t we, we to a multibyte character, 
FILE “stream); and writes it to the stream at 
the current position. 
putwchar® wchar.h wint_t Converts the wide character 
putwchar(wchar_t we); | we to a multibyte character 
and writes it to stdout. 
qsort stdlib.h void qsort(void *base, Performs a quick sort of an 
size_t num, size_t width, | array of num elements, each of 
int(*compare)(const void | width bytes in size. 
*element1, const void 
*element2)); 
raise signal.h int raise(int sig); Sends the signal sig to the 
running program. 
rand stdlib.h int rand(void); Returns a pseudo-random 
integer. 
rand_r stdlib.h int rand_r(void); Returns a pseudo-random 
integer. (Restartable version) 
realloc stdlib.h void *realloc(void *ptr, | Changes the size of a 
size_t size); previously reserved storage 
block. 
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regcomp regex.h int regcomp(regex_t Compiles the source regular 
*preg, const char expression pointed to by 
*pattern, int cflags); pattern into an executable 
version and stores it in the 
location pointed to by preg. 
regerror regex.h size_t regerror(int Finds the description for the 
errcode, const regex_t error code errcode for the 
*preg, char “errbuf, size_t | regular expression preg. 
errbuf_size); 
regexec regex.h int regexec(const regex_t | Compares the null-ended 
*preg, const char “string, | string string against the 
size_t nmatch, compiled regular expression 
regmatch_t *pmatch, int | preg to find a match between 
eflags); the two. 
regfree regex.h void regfree(regex_t Frees any memory that was 
*preg); allocated by regcomp to 
implement the regular 
expression preg. 
remove stdio.h int remove(const char Deletes the file specified by 
*filename); filename. 
rename stdio.h int rename(const char Renames the specified file. 
*oldname, const char 
*newname); 
rewind! stdio.h void rewind(FILE Repositions the file pointer 
*stream); associated with stream to the 
beginning of the file. 
scanf stdio.h int scanf(const char Reads data from stdin into 
*format-string, arg-list); | locations given by arg-list. 
setbuf stdio.h void setbuf(FILE Controls buffering for stream. 
*stream, char *buffer); 
setjmp setjimp.h int setjmp(jmp_buf env); | Saves a stack environment 
that can be subsequently 
restored by longjmp. 
setlocale locale.h char *setlocale(int Changes or queries variables 
category, const char defined in the locale. 
*locale); 
setvbuf stdio.h int setvbuf(FILE “stream, | Controls buffering and buffer 
char *buf, int type, size_t | size for stream. 
size); 
signal signal.h void(*signal (int sig, Registers func as a signal 
void(*func)(int))) (int); handler for the signal sig. 
sin math.h double sin(double x); Calculates the sine of x. 
sinh math.h double sinh(double x); | Calculates the hyperbolic sine 
of x. 
snprintf stdio.h int snprintf(char Same as sprintf except that the 


*outbuf, size_t n, const 
char’, ...) 


function will stop after n 
characters have been written 
to outbuf. 
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sprintf stdio.h int sprintf(char *buffer, | Formats and stores characters 
const char *format-string, | and values in buffer. 
arg-list); 
sqrt math.h double sqrt(double x); Calculates the square root of 
Xx. 
srand stdlib.h void srand(unsigned int | Sets the seed for the 
seed); pseudo-random number 
generator. 
sscanf stdio.h int sscanf(const char Reads data from buffer into the 
“buffer, const char locations given by arg-list. 
*format, arg-list); 
strcasecmp strings.h int srtcasecmp(const Compares strings without case 
char *string1, const char | sensitivity. 
*string2); 
streat string.h char *strcat(char Concatenates string2 to string1. 
*string1, const char 
*string2); 
strchr string.h char *strchr(const char | Locates the first occurrence of 
*string, int c); c in string. 
strcmp string.h int stremp(const char Compares the value of string] 
*string1, const char to string2. 
*string2); 
strcoll string.h int strcoll(const char Compares two strings using 
*string1, const char the collating sequence in the 
*string2); current locale. 
strcpy string.h char *strepy(char Copies string2 into string1. 
*string1, const char 
*string2); 
strespn string.h size_t strespn(const char | Returns the length of the 
*string1, const char initial substring of string] 
*string2); consisting of characters not 
contained in string2. 
strerror string.h char *strerror(int Maps the error number in 
errnum); errnum to an error message 
string. 
strfmon* wchar.h int strfmon (char *s, Converts monetary value to 
size_t maxsize, const string. 
char *format, ...); 
strftime time.h size_t strftime (char Stores characters in an array 
*dest, size_t maxsize, pointed to by dest, according 
const char *format, const | to the string determined by 
struct tm *timeptr); format. 
strlen string.h size_t strlen(const char | Calculates the length of string. 
*string); 
strncasecmp strings.h int srtncasecmp(const Compares strings without case 
char *string1, const char | sensitivity. 
*string2, size_t count); 
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strncat string.h char *strncat(char Concatenates up to count 
*string1, const char characters of string2 to string1. 
*string2, size_t count); 
strncmp string.h int strncmp(const char |Compares up to count 
*string1, const char characters of string] and 
*string2, size_t count); string2. 
strncpy string.h char *strncpy(char Copies up to count characters 
*string1, const char of string2 to string1. 
*string2, size_t count); 
strpbrk string.h char *strpbrk(const char | Locates the first occurrence in 
*string1, const char string] of any character in 
*string2); string2. 
strptime* time.h char *strptime (const Date and time conversion 
char *buf, const char 
*format, struct tm *tm); 
strrchr string.h char *strrchr(const char | Locates the last occurrence of 
*string, int c); c in string. 
strspn string.h size_t strspn(const char | Returns the length of the 
*string1, const char initial substring of string] 
*string2); consisting of characters 
contained in string2. 
strstr string.h char *strstr(const char Returns a pointer to the first 
*string1, const char occurrence of string2 in 
*string2); string1. 
strtod stdlib.h double strtod(const char | Converts nptr to a double 
*nptr, char **endptr); precision value. 
strtok string.h char *strtok(char Locates the next token in 
*string1, const char string] delimited by the next 
*string2); character in string2. 
strtok_r string.h char *strtok_r(char Locates the next token in 
*string, const char *seps, | string delimited by the next 
char **lasts); character in seps. (Restartable 
version of strtok.) 
strtol stdlib.h long int strtol(const char | Converts nptr to a signed long 
*nptr, char *“endptr, int | integer. 
base); 
strtoul stdlib.h unsigned long int Converts string1 to an 
strtoul(const char unsigned long integer. 
*string1, char **string2, 
int base); 
strxfrm string.h size_t strxfrm(char Converts string2 and places 
*string1, const char the result in string1. The 
*string2, size_t count); conversion is determined by 
the program’s current locale. 
swprintf wchar.h int swprintf(wchar_t Formats and stores a series of 


*wesbuffer, size_t n, const 
wchar_t “format, arg-list); 


wide characters and values 
into the wide-character buffer 
wesbuffer. 
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swscanf wchar.h int swscanf (const Reads data from buffer into the 
wchar_t *buffer, const locations given by arg-list. 
wchar_t *format, arg-list) 
system stdlib.h int system(const char Passes string to the system 
*string); command analyzer. 
tan math.h double tan(double x); Calculates the tangent of x. 
tanh math.h double tanh(double x); | Calculates the hyperbolic 
tangent of x. 
time time.h time_t time(time_t Returns the current calendar 
*timeptr); time. 
tmpfile stdio.h FILE *tmpfile(void); Creates a temporary binary 
file and opens it. 
tmpnam stdio.h char *tmpnam(char Generates a temporary file 
*string); name. 
toascii ctype.h int toascii(int c); Converts c to a character in 
the 7-bit US-ASCII character 
set. 
tolower ctype.h int tolower(int c); Converts c to lowercase. 
toupper ctype.h int toupper(int c); Converts c to uppercase. 
towctrans wctype.h wint_t towctrans(wint_t | Translates the wide character 
we, wctrans_t desc); we based on the mapping 
described by desc. 
towlower* wctype.h wint_t towlower (wint_t | Converts uppercase letter to 
we); lowercase letter. 
towupper* wctype.h wint_t towupper (wint_t | Converts lowercase letter to 
we); uppercase letter. 
ungetc! stdio.h int ungetc(int c, FILE Pushes c back onto the input 
*stream); stream. 
ungetwc® stdio.h wint_t ungetwc(wint_t | Pushes the wide character we 
wchar.h we, FILE *stream); back onto the input stream. 
va_arg stdarg.h var_type va_arg(va_list | Returns the value of one 
arg_ptr, var_type); argument and modifies arg_ptr 
to point to the next argument. 
va_end stdarg.h void va_end(va_list Facilitates normal return from 
arg_ptr); variable argument list 
processing. 
va_start stdarg.h void va_start(va_list Initializes arg_ptr for 
arg_ptr, variable_name); subsequent use by va_arg and 
va_end. 
vfprintf stdio.h int vfprintf(FILE *stream, | Formats and prints characters 
stdarg.h const char *format, to the output stream using a 
va_list arg_ptr); variable number of arguments. 
vfwprintf® stdarg.h int vfwprintf(FILE Equivalent to fwprintf, except 
stdio.h *stream, const wchar_t _ | that the variable argument list 
wchar.h *format, va_list arg); is replaced by arg. 
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Table 32. Standard C Library Functions (continued) 


System 
Function Include File | Function Prototype Description 
vprintf stdio.h int vprintf(const char Formats and prints characters 
stdarg.h *format, va_list arg_ptr); | to stdout using a variable 
number of arguments. 
vsprintf stdio.h int vsprintf(char Formats and stores characters 
stdarg.h *target-string, const char |in a buffer using a variable 
*format, va_list arg_ptr); |number of arguments. 
vsnprintf stdio.h int vsnprintf(char Same as vsprintf except that 
*outbuf, size_t n, const | the function will stop after n 
char*, va_list); characters have been written 
to outbuf. 
vswprintf stdarg.h int vswprintf(wchar_t Formats and stores a series of 
wchar.h *wesbuffer, size_t n, const | wide characters and values in 
wchar_t “format, va_list | the buffer wesbuffer. 
arg); 
vwprintf® stdarg.h int vwprintf(const Equivalent to wprintf, except 
wchar.h wchar_t “format, va_list | that the variable arument list 
arg); is replaced by arg. 
wertomb* wchar.h int wcrtomb (char *s, Converts a wide character to a 
wchar_t wchar, multibyte character. 
mbstate_t *pss); (Restartable version of 
wctomb.) 
wescat westr.h wchar_t Appends a copy of the string 
*wescat(wchar_t pointed to by string2 to the 
*string1, const wchar_t | end of the string pointed to by 
*string2); string1. 
weschr westr.h wchar_t *weschr(const | Searches the wide-character 
wchar_t *string, wchar_t | string pointed to by string for 
character); the occurrence of character. 
wescmp westr.h int wescmp(const Compares two wide-character 
wchar_t *string1, const | strings, *string1 and “string2. 
wchar_t *string2); 
wescoll* wchar.h int wescoll (const Compares two wide-character 
wchar_t *wes1, const strings using the collating 
wchar_t *wecs2); sequence in the current locale. 
wescpy westr.h wchar_t Copies the contents of *string2 
*wescpy(wchar_t (including the ending wchar_t 
*string1, const wchar_t | null character) into “string1. 
*string2); 
wescspn westr.h size_t wcscspn(const Determines the number of 
wchar_t “string1, const | wchar_t characters in the 
wchar_t *string2); initial segment of the string 
pointed to by *string1 that do 
not appear in the string 
pointed to by *string2. 
wesftime wchar.h size_t wesftime(wchar_t | Converts the time and date 
*wdest, size_t maxsize, specification in the timeptr 
const wchar_t “format, structure into a wide-character 
const struct tm *timeptr); | string. 
weslen westr.h size_t wcslen(const Computes the number of 


wchar_t “*string); 


wide-characters in the string 
pointed to by string. 
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Table 32. Standard C Library Functions (continued) 


System 
Function Include File | Function Prototype Description 
wesncat westr.h wchar_t Appends up to count wide 
*wesncat(wchar_t characters from string2 to the 
*string1, const wchar_t | end of string1, and appends a 
*string2, size_t count); wchar_t null character to the 
result. 
wcsnemp westr.h int wcesncmp(const Compares up to count wide 
wchar_t *string1, const | characters in string1 to string2. 
wchar_t “string2, size_t 
count); 
wcsncpy westr.h wchar_t Copies up to count wide 
*wesncpy(wchar_t characters from string2 to 
*string1, const wchar_t | string1. 
*string2, size_t count); 
wespbrk westr.h wchar_t *wespbrk(const | Locates the first occurrence in 
wchar_t *string1, const | the string pointed to by 
wchar_t “string2); string] of any wide characters 
from the string pointed to by 
string2. 
wesrchr westr.h wchar_t *wesrchr(const |Locates the last occurrence of 
wchar_t *string, wchar_t | character in the string pointed 
character); to by string. 
wesrtombs* wchar.h size_t wcesrtombs (char | Converts wide character string 
*dst, const wchar_t to multibyte string. 
**src, size_t len, (Restartable version of 
mbstate_t *ps); wcstombs.) 
wcsspn wchar.h size_t wcsspn(const Computes the number of wide 
wchar_t *string1, const | characters in the initial 
wchar_t *string2); segment of the string pointed 
to by string1, which consists 
entirely of wide characters 
from the string pointed to by 
string2. 
wesstr wchar.h wchar_t *wesstr(const Locates the first occurrence of 
wchar_t *wcs1, const wes2 in wesl. 
wchar_t *wes2); 
westod wchar.h double wcstod(const Converts the initial portion of 
wchar_t *nptr, wchar_t | the wide-character string 
“endptr); pointed to by nptr to a double 
value. 
westok wchar.h wchar_t Breaks wes1 into a sequence of 
*westok(wchar_t *wcs1, | tokens, each of which is 
const wchar_t *wes2, delimited by a wide character 
wchar_t *“ptr) from the wide string pointed 
to by wes2. 
westol wchar.h long int westol(const Converts the initial portion of 
wchar_t *nptr, wchar_t | the wide-character string 
“endptr, int base); pointed to by nptr to a long 
integer value. 
wcstombs stdlib.h size_t wcstombs(char Converts the wchar_t string 
*dest, const wchar_t into a multibyte string dest. 
*string, size_t count); 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


Table 32. Standard C Library Functions (continued) 


System 
Function Include File | Function Prototype Description 
westoul wchar.h unsigned long int Converts the initial portion of 
westoul(const wchar_t | the wide-character string 
*nptr, wchar_t *“endptr, | pointed to by nptr to an 
int base); unsigned long integer value. 
wesxfrm* wehar.h size_t wesxfrm (wchar_t | Transforms a wide-character 
*wesl, const wchar_t string to values which 
*wes2, size_t n); represent character collating 
weights and places the 
resulting wide-character string 
into an array. 
wctob stdarg.h int wctob(wint_t we); Determines whether we 
wchar.h corresponds to a member of 
the extended character set 
whose multibyte character 
representation is a single byte 
when in the initial shift state. 
wctomb stdlib.h int wctomb(char *string, | Converts the wchar_t value of 
wchar_t character); character into a multibyte 
string. 
wctrans wctype.h wctrans_t wctrans(const | Constructs a value with type 
char *property); wctrans_t that describes a 
mapping between wide 
characters identified by the 
string argument property. 
wctype* wchar.h wctype_t wctype (const | Obtains handle for character 
char “property); property classification. 
wewidth wchar.h int weswidth(const Determine the display width 
wchar_t *pwes, size_t n); | of a wide character string. 
wmemchr wchar.h wchar_t Locates the first occurrence of 
*wmemchr(const c in the initial n wide 
wchar_t *s, wchar_t c, characters of the object 
size_t n); pointed to by s. 
wmemcmp wchar.h int wmemcmp(const Compares the first n wide 
wchar_t *s1, const characters of the object 
wchar_t “s2, size_t n); pointed to by s1 to the first n 
characters of the object 
pointed to by s2. 
wmemcpy wchar.h wchar_t Copies 1 wide characters from 
*wmemcpy(wchar_t *s1, | the object pointed to by s2 to 
const wchar_t *s2, size_t | the object pointed to by s1. 
n); 
wmemmove wchar.h wchar_t Copies 1 wide characters from 
*wmemmove(wchar_t | the object pointed to by s2 to 
*s1, const wchar_t “*s2, the object pointed to by s1. 
size_t n); 
wmemset wchar.h wchar_t Copies the value of c into each 


*wmemset(wchar_t *s, 
wchar_t c, size_t n); 


of the first n wide chracters of 
the object pointed to by s. 
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Table 32. Standard C Library Functions (continued) 


Function 


wprintf® 


System 
Include File 


wchar.h 


Function Prototype 


int wprintf(const 
wchar_t “format, arg-list); 


Description 


Equivalent to fwprintf with 
the argument stdout 
interposed before the 
arguments to wprintt. 


wscanf° 


wchar.h 


int wscanf(const 
wchar_t *format, arg-list); 


Equivalent to fwscanf with the 
argument stdin interposed 
before the arguments of 
wscanf. 


math.h 


double y0(double x); 


Calculates the Bessel function 
value of the second kind of 
order 0. 


yl 


math.h 


double y1(double x); 


Calculates the Bessel function 
value of the second kind of 
order 1. 


yn 


math.h 


double yn(int n, double 
Xx); 


Calculates the Bessel function 
value of the second kind of 
order n. 


ILE C Library Extensions to C Library Functions Table 


This table briefly describes all the ILE C library extensions, listed in alphabetical 
order. This table provides the include file name, and the function prototype for 
each function. 


Table 33. ILE C Library Extensions 


System Include 


Function file Function prototype Description 

_C_Get stdio.h _SSN_Handle_T Returns a handle to 

_Ssn_Handle _C_Get_Ssn_Handle (void); | the C session for use 
with DSM APIs. 

_C TS stdlib.h void Same as 

_malloc64 * C_TS_malloc64(unsigned _C_TS_malloc, but 

long long int); takes an unsigned 

long long int so the 
user can ask for more 
than 2 GB of storage 
on a single request. 

_C_TS mallocinfo.h void *malloc(size_t size); Returns current 


_malloc_info 


memory usage 
information. 


_C_TS 
_malloc_debug 


mallocinfo.h 


void *malloc(size_t size); 


Returns the same 
information as 
_C_TS_malloc_info, 
plus produces a spool 
file of detailed 
information about the 
memory structure 
used by C_TS_malloc 
functions. 
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Table 33. ILE C Library Extensions (continued) 


System Include 


Function file Function prototype Description 

_GetExcData signal.h void _GetExcData Retrieves information 
(_INTRPT_Hndlr_Parms_T about an exception 
*parms); from within a signal 

handler. 

QXXCHGDA xxdtaa.h void Changes the OS/400 
QXXCHGDA(_DTAA_NAME |Hata area specified on 
dtaname, short int offset, short | dtaname using the data 
int len, char *dtaptr); pointed to by dtaptr. 

QXXDTOP xxevt.h void OXXDTOP(unsigned Converts a double 
char “pptr, int digits, int value to a packed 
fraction, double value); decimal value with 

digits total digits and 
fraction fractional 
digits. 

QOXXDTOZ xxevt.h void OXXDTOZ(unsigned Converts a double 
char *zptr, int digits, int value to a zoned 
fraction, double value); decimal value with 

digits total digits and 
fraction fractional 
digits. 

QXXITOP xxcvt.h void OXXITOP(unsigned Converts an integer 
char “pptr, int digits, int value to a packed 
fraction, int value); decimal value. 

QXXITOZ xxevt.h void OXXITOZ(unsigned Converts an integer 
char *zptr, int digits, int value to a zoned 
fraction, int value); decimal value. 

QXXPTOD xxevt.h double QXXPTOD(unsigned | Converts a packed 
char “pptr, int digits, int decimal number to a 
fraction ); double value with 

digits total digits and 
fraction fractional 
digits. 

QXXPTOI xxevt.h int OXXPTOl(unsigned char | Converts a packed 
*pptr, int digits, int fraction ); | decimal number to an 

integer value with 
digits total digits and 
fraction fractional 
digits. 

QXXRTVDA xxdtaa.h void Retrieves a copy of 
QOXXRTVDA(_DTAA_NAME_Tthe OS/400 data area 
dtaname, short int offset, short | specified on dtaname. 
int len, char “dtaptr); 

QOXXZTOD xxevt.h double QXXZTOD(unsigned | Converts a zoned 


char *zptr, int digits, int 
fraction ); 


decimal number to a 
double value with 
digits total digits and 
fraction fractional 
digits. 
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Table 33. ILE C Library Extensions (continued) 


System Include 
Function file Function prototype Description 
OXXZTOI xxevt.h int OXXZTOI(unsigned char | Converts a zoned 
*zptr, int digits, int fraction ); | decimal value to an 

integer value with 
digits total digits and 
fraction fractional 
digits. 

_Racquire recio.h int _Racquire(_RFILE “fp, Prepares a device for 

char *dev); record I/O operations. 

_Rclose recio.h int _Rclose(_RFILE “fp); Closes a file that is 
opened for record I/O 
operations. 

_Rcommit recio.h int _Rcommit(char *cmtid); Completes the current 
transaction, and 
establishes a new 
commitment 
boundary. 

_Rdelete recio.h RIOFB_T *_Rdelete(_RFILE | Deletes the currently 

*fp); locked record. 

_Rdevatr xxfdbk.h recio.h | XXDEV_ATR_T Returns a pointer to a 

* Rdevatr(_RFILE “fp, char copy of the device 

*pgmdev); attributes feedback 
area for the file 
referenced by fp and 
the device pgmdev. 

_Rfeod recio.h int _Rfeod(_RFILE “fp); Forces an end-of-file 
condition for the file 
referenced by fp. 

_Rfeov recio.h int _Rfeov(_RFILE “fp); Forces an 
end-of-volume 
condition for the tape 
file referenced by fp. 

_Rformat recio.h void Rformat(_RFILE “fp, Sets the record format 

char “fmt); to fmt for the file 
referenced by fp. 

_Rindara recio.h void _Rindara (_RFILE “fp, Sets up the separate 

char *indic_buf); indicator area to be 
used for subsequent 
record I/O operations. 

_Riofbk recio.h xxfdbk.h | _XXIOFB_T *_Riofbk(_RFILE | Returns a pointer to a 

*fp); copy of the I/O 
feedback area for the 
file referenced by fp. 

_Rlocate recio.h RIOFB_T *_Rlocate(_RFILE | Positions to the record 

“fp, void “key, int klen_rrn, int |in the file associated 

opts); with fp and specified 
by the key, klen_rrn 
and opt parameters. 

_Ropen recio.h _RFILE *_Ropen(const char | Opens a file for record 

“filename, const char “mode I/O operations. 
x) 
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Table 33. ILE C Library Extensions (continued) 


System Include 


Function file Function prototype Description 
_Ropnfbk recio.h xxfdbk.h | XXOPFB_T Returns a pointer to a 
* Ropnfbk(_RFILE “*fp); copy of the open 
feedback area for the 
file referenced by fp. 
_Rpgmdev recio.h int _Rpgmdev(_RFILE “fp, Sets the default 
char *dev); program device. 
_Rreadd recio.h RIOFB_T *_Rreadd(_RFILE | Reads a record by 
*fp, void “buf, size_t size, int | relative record 
opts, long rrn); number. 
_Rreadf recio.h RIOFB_T *_Rreadf(_RFILE | Reads the first record. 
*fp, void “buf, size_t size, int 
opts); 
_Rreadindv recio.h _RIOFB_T Reads a record from 
* Rreadindv(_RFILE “fp, void | an invited device. 
*buf, size_t size, int opts); 
_Rreadk recio.h RIOFB_T *_Rreadk(_RFILE | Reads a record by key. 
“fp, void “buf, size_t size, int 
opts, void *key, int klen); 
_Rread1 recio.h RIOFB_T *_Rreadl(_RFILE | Reads the last record. 
*fp, void “buf, size_t size, int 
opts); 
_Rreadn recio.h RIOFB_T *_Rreadn(_RFILE | Reads the next record. 
*fp, void “buf, size_t size, int 
opts); 
_Rreadnc recio.h _RIOFB_T *_Rreadnc(_RFILE | Reads the next 
*fp, void “buf, size_t size); changed record in the 
subfile. 
_Rreadp recio.h RIOFB_T *_Rreadp(_RFILE | Reads the previous 
*fp, void “buf, size_t size, int | record. 
opts); 
_Rreads recio.h RIOFB_T *_Rreads(_RFILE | Reads the same 
*fp, void “buf, size_t size, int | record. 
opts); 
_Rrelease recio.h int _Rrelease(_RFILE “fp, char | Makes the specified 
*dev); device ineligible for 
record I/O operations. 
_Rrlslck recio.h int _Rrlslck(_RFILE *fp); Releases the currently 
locked record. 
_Rrollbck recio.h int _Rrollbck(void); Reestablishes the last 
commitment 
boundary as the 
current commitment 
boundary. 
_Rupdate recio.h _RIOFB_T *_Rupdate(_RFILE | Writes to the record 


“fp, void “buf, size_t size); 


that is currently 
locked for update. 
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Table 33. ILE C Library Extensions (continued) 


System Include 
Function file Function prototype Description 
_Rupfb recio.h RIOFB_T *_Rupfb(_RFILE Updates the feedback 
*fp); structure with 
information about the 
last record I/O 
operation. 
_Rwrite recio.h RIOFB_T *_Rwrite(_RFILE Writes a record to the 
*fp, void “buf, size_t size); end of the file. 
_Rwrited recio.h _RIOFB_T *_Rwrited(_RFILE | Writes a record by 
*fp, void *buf, size_t size, relative record 
unsigned long rrn); number. It only writes 
over deleted records. 
_Rwriterd recio.h _RIOFB_T *_Rwriterd(_RFILE | Reads and writes a 
*fp, void “buf, size_t size); record. 
_Rwrread recio.h _RIOFB_T *_Rwrread(_RFILE | Functions as 
*fp, void *inbuf, size_t _Rwriterd, except 
in_buf_size, void *out_buf, separate buffers may 
size_t out_buf_size); be specified for input 
and output data. 
__wcsicmp wchar.h int __wcsicmp(const wchar_t |Compares wide 
*string1, const wchar_t character strings 
*string2); without case 
sensitivity. 
__wcsnicmp wchar.h int __wcsnicmp(const Compares wide 
wchar_t *string1, const character strings 
wchar_t *string2, size_t without case 
count); sensitivity. 
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Appendix B. Notices 


This information was developed for products and services offered in the U.S.A. 
IBM may not offer the products, services, or features discussed in this document in 
other countries. Consult your local IBM representative for information on the 
products and services currently available in your area. Any reference to an IBM 
product, program, or service is not intended to state or imply that only that IBM 
product, program, or service may be used. Any functionally equivalent product, 
program, or service that does not infringe any IBM intellectual property right may 
be used instead. However, it is the user’s responsibility to evaluate and verify the 
operation of any non-IBM product, program, or service. 


IBM may have patents or pending patent applications covering subject matter 
described in this document. The furnishing of this document does not give you 
any license to these patents. You can send license inquiries, in writing, to: 


IBM Director of Licensing 
IBM Corporation 

500 Columbus Avenue 
Thornwood, NY 10594. 
U.S.A. 


For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 


IBM World Trade Asia Corporation 
Licensing 

2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106-0032, Japan 


The following paragraph does not apply to the United Kingdom or any other 
country where such provisions are inconsistent with local law: 
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS 
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or 
implied warranties in certain transactions, therefore, this statement may not apply 
to you. 


This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the publication. IBM may make improvements 
and/or changes in the product(s) and/or the program(s) described in this 
publication at any time without notice. 


Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any manner serve as an endorsement of those Web 
sites. The materials at those Web sites are not part of the materials for this IBM 
product and use of those Web sites is at your own risk. 


Licensees of this program who wish to have information about it for the purpose 
of enabling: (i) the exchange of information between independently created 
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programs and other programs (including this one) and (ii) the mutual use of the 
information which has been exchanged, should contact: 


IBM Corporation 

Software Interoperability Coordinator 
3605 Highway 52 N 

Rochester, MN 55901-7829 

Las 


Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 


The licensed program described in this information and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM International Program License Agreement, or any equivalent agreement 
between us. 


Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments may 
vary significantly. Some measurements may have been made on development-level 
systems and there is no guarantee that these measurements will be the same on 
generally available systems. Furthermore, some measurements may have been 
estimated through extrapolation. Actual results may vary. Users of this document 
should verify the applicable data for their specific environment. 


Information concerning non-IBM products was obtained from the suppliers of 
those products, their published announcements or other publicly available sources. 
IBM has not tested those products and cannot confirm the accuracy of 
performance, compatibility or any other claims related to non-IBM products. 
Questions on the capabilities of non-IBM products should be addressed to the 
suppliers of those products. 


All statements regarding IBM’s future direction or intent are subject to change or 
withdrawal without notice, and represent goals and objectives only. 


All IBM prices shown are IBM’s suggested retail prices, are current and are subject 
to change without notice. Dealer prices may vary. 


This information is for planning purposes only. The information herein is subject to 
change before the products described become available. 


This information contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


COPYRIGHT LICENSE: 


This information contains sample application programs in source language, which 
illustrate programming techniques on various operating platforms. You may copy, 
modify, and distribute these sample programs in any form without payment to 
IBM, for the purposes of developing, using, marketing or distributing application 
programs conforming to the application programming interface for the operating 
platform for which the sample programs are written. These examples have not 
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or 
imply reliability, serviceability, or function of these programs. You may copy, 


ILE C/C++ for iSeries Run-Time Library Functions V5R2 


modify, and distribute these sample programs in any form without payment to 
IBM for the purposes of developing, using, marketing, or distributing application 
programs conforming to IBM’s application programming interfaces. 


Each copy or any portion of these sample programs or any derivative work, must 
include a copyright notice as follows: 


© (your company name) (year). Portions of this code are derived from IBM Corp. 
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights 
reserved. 


If you are viewing this information softcopy, the photographs and color 
illustrations may not appear. 


Programming Interface Information 


This publication is intended to help you to write Integrated Language Environment 
C/C++ for OS/400 programs. It contains information necessary to use the 
Integrated Language Environment C/C++ for the OS/400 compiler. The iL 
Pics. Pmgrammera Guidd primarily documents general-use programming 
interfaces and associated guidance information provided by the Integrated 
Language Environment C/C++ for the OS/400 compiler. 


Trademarks 


The following terms are trademarks of International Business Machines 
Corporation in the United States, other countries, or both: 


Application System /400 
AS/400 

e (logo) 

IBM 

iSeries 

Operating System/400 
OS/400 

400 


C-bus is a trademark of Corollary, Inc. in the United States, other countries, or 
both. 


Java and all Java-based trademarks and logos are trademarks or registered 
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. 


Microsoft, Windows, Windows NT, and the Windows logo are trademarks of 
Microsoft Corporation in the United States, other countries, or both. 


PC Direct is a trademark of Ziff Communications Company in the United States, 
other countries, or both and is used by IBM Corporation under license. 


ActionMedia, LANDesk, MMX, Pentium, and ProShare are trademarks of Intel 
Corporation in the United States, other countries, or both. 


UNIX is a registered trademark of The Open Group in the United States and other 
countries. 


Appendix B. Notices 497 


SET and the SET Logo are trademarks owned by SET Secure Electronic Transaction 
LLC. 


Other company, product, and service names may be trademarks or service marks 
of others. 
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For additional information about topics related to 
ILE C programming on the iSeries system, refer to 
the following IBM iSeries publications: 


¢ WebSphere Development Studio: Application 
Development Manager User's Guide, 
SC09-2133-02, describes creating and managing 
projects defined for the Application 
Development Manager /400 feature, as well as 
using the program to develop applications. 


* ADTS/400: Programming Development Manager, 
SC09-1771-00, provides information about using 
the Application Development ToolSet/400 
programming development manager (PDM) to 
work with lists of libraries, objects, members, 
and user-defined options to easily do such 
operations as copy, delete, and rename. 
Contains activities and reference material to 
help the user learn PDM. The most commonly 
used operations and function keys are 
explained in detail using examples. 


* ADTS for AS/400: Source Entry Utility, 
SC09-2605-00, provides information about using 
the Application Development ToolSet/400 
source entry utility (SEU) to create and edit 
source members. The manual explains how to 
start and end an SEU session and how to use 
the many features of this full-screen text editor. 
The manual contains examples to help both 
new and experienced users accomplish various 
editing tasks, from the simplest line commands 
to using pre-defined prompts for high-level 
languages and data formats. 

* Application Display Programming, SC41-5715-00, 
provides information about: 

— Using DDS to create and maintain displays 
for applications; 


— Creating and working with display files on 
the system; 


— Creating online help information; 


— Using UIM to define panels and dialogs for 
an application; 


— Using panel groups, records, or documents 


* The Information Center 
topic provides information about setting up 
and managing the following: 


— Journaling, access path protection, and 
commitment control 


— User auxiliary storage pools (ASPs) 
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— Disk protection (device parity, mirrored, and 
checksum) 


Provides performance information about 
backup media and save/restore operations. 
Also includes advanced backup and recovery 
topics, such as using save-while-active support, 
saving and restoring to a different release, and 
programming tips and techniques. 


CICS for iSeries Application Programming Guide, 
$C41-5454-01, provides information on 
application programming for CICS/400®. It 
includes guidance and reference information on 
the CICS application programming interface 
and system programming interface commands, 
and gives general information about 
developing new applications and migrating 
existing applications from other CICS 
platforms. 


ILE C/C++ for AS/400 MI Library Reference, 
SC09-2418-00, provides information on Machine 
Interface instructions available in the ILE C 
compiler that provide system-level 
programming capabilities. 

CL Programming, SC41-5721-05, provides a 
wide-ranging discussion of iSeriesprogramming 
topics including a general discussion on objects 
and libraries, CL programming, controlling 
flow and communicating between programs, 
working with objects in CL programs, and 
creating CL programs. Other topics include 
predefined and impromptu messages and 
message handling, defining and creating 
user-defined commands and menus, application 
testing, including debug mode, breakpoints, 
traces, and display functions. 


The CL Referencd topic provides a description 
of the iSeriescontrol language (CL) and its 
OS/400 commands. (Non-OS/400 commands 
are described in the respective licensed 
program publications.) Also provides an 
overview of all the CL commands for the 
iSeries system, and it describes the syntax rules 
needed to code them. 

Communications Management, SC41-5406-02, 
provides information about work management 
in a communications environment, 
communications status, tracing and diagnosing 
communications problems, error handling and 
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recovery, performance, and specific line speed 
and subsystem storage information. 


The Information Center topic 
provides information about using files in 
application programs. Includes information on 
the following: 


— Fundamental structure and concepts of data 
management support on the system 


— Overrides and file redirection (temporarily 
making changes to files when an application 
program is run) 


— Copying files by using system commands to 
copy data from one place to another 


— Tailoring a system using double-byte data 


The topic provides a 
detailed discussion of the iSeries database 
organization, including information on how to 
create, describe, and update database files on 
the system. Also describes how to define files 
to the system using OS/400 data description 
specifications (DDS) keywords. 

The EQL Programming topic provides 
information about how to use DB2® Query 
Manager and SQL Development kit licensed 
program. Shows how to access data in a 
database library and prepare, run, and test an 
application program that contains embedded 
SQL statements. Contains examples of 
SQL/400® statements and a description of the 
interactive SQL function. Describes common 
concepts and rules for using SQL/400 
statements in ILE COBOL, PL/I, ILE C, 
FORTRAN/400®, ILE RPG/400, and REXX. 


The BQL Reference topic provides information 


about how to use Structured Query 
Language/400 DB2 statements and gives details 
about the proper use of the statements. 
Examples of statements include syntax 
diagrams, parameters, and definitions. A list of 
SQL limits and a description of the SQL 
communication area (SQLCA) and SQL 
descriptor area (SQLDA) are also provided. 


The DDS Referencel topic provides detailed 
descriptions for coding the data description 
specifications (DDS) for file that can be 
described externally. These files are physical, 
logical, display, print, and intersystem 
communication function (ICF) files. 

The Distributed Data Management topic 
provides information about remote file 
processing. It describes how to define a remote 
file to OS/400 distributed data management 
(DDM), how to create a DDM file, what file 
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utilities are supported through DDM, and the 
requirements of OS/400 DDM as related to 
other systems. 


Experience RPG IV Multimedia Tutorial, 
SK2T-2700, is an interactive self-study program 
explaining the differences between RPG III and 
RPG IV and how to work within the new ILE 
environment. An accompanying workbook 
provides additional exercises and doubles as a 
reference upon completion of the tutorial. ILE 
RPG code examples are shipped with the 
tutorial and run directly on the iSeries. 


GDDM Programming Guide, SC41-0536-00, 
provides information about using 
OS/400graphical data display manager 
(GDDM") to write graphics application 
programs. Includes many example programs 
and information to help users understand how 
the product fits into data processing systems. 


GDDM Reference, SC41-3718-00, provides 
information about using OS/400graphical data 
display manager (GDDM) to write graphics 
application programs. This manual provides 
detailed descriptions of all graphics routines 
available in GDDM. Also provides information 
about high-level language interfaces to GDDM. 


ICF Programming, SC41-5442-00, provides 
information needed to write application 
programs that use iSeries communications and 
the OS/400 intersystem communications 
function (OS/400-ICF). Also contains 
information on data description specifications 
(DDS) keywords, system-supplied formats, 
return codes, file transfer support, and program 
examples. 


IDDU Use, SC41-5704-00, describes how to use 
the iSeries interactive data definition utility 
(IDDU) to describe data dictionaries, files, and 
records to the system. Includes: 


— An introduction to computer file and data 
definition concepts 


— An introduction to the use of IDDU to 
describe the data used in queries and 
documents 


— Representative tasks related to creating, 
maintaining, and using data dictionaries, 
files, record formats, and fields 


— Advanced information about using IDDU to 
work with files created on other systems and 
information about error recovery and 
problem prevention. 


WebSphere Development Studio: ILE C/C++ 
Programmer's Guide, SC09-2712-03, provides 


information on how to develop applications 
using the ILE C language. It includes 
information about creating, running and 
debugging programs. It also includes 
programming considerations for interlanguage 
program and procedure calls, locales, handling 
exceptions, database, externally described and 
device files. Some performance tips are also 
described. An appendix includes information 
on migrating source code from EPM C or 
System C to ILE C. 


ILE C for AS/400 Language Reference, 
SC09-2711-01, provides reference information 
about ILE C, including elements of the 
language, statements, and preprocessor 
directives. Examples are provided and 
considerations for programming are also 
discussed. 


WebSphere Development Studio: ILE COBOL 
Programmer's Guide, SCO09-2540-03, provides 
information about how to write, compile, bind, 
run, debug, and maintain ILE COBOL 
programs on the iSeries system. It provides 
programming information on how to call other 
ILE COBOL and non-ILE COBOL programs, 
share data with other programs, use pointers, 
and handle exceptions. It also describes how to 
perform input/output operations on externally 
attached devices, database files, display files, 
and ICF files. 


WebSphere Development Studio: ILE COBOL 
Reference, SC09-2539-03, provides a description 
of the ILE COBOL programming language. It 
provides information on the structure of the 
ILE COBOL programming language and the 
structure of an ILE COBOL source program. It 
also provides a description of all Identification 
Division paragraphs, Environment Division 
clauses, Data Division clauses, Procedure 
Division statements, and Compiler-Directing 
statements. 


WebSphere Development Studio: ILE COBOL 
Reference Summary, SX09-1317-03, provides 
quick reference information on the structure of 
the ILE COBOL programming language and 


the structure of an ILE COBOL source program. 


It also provides syntax diagrams of all 
Identification Division paragraphs, 
Environment Division clauses, Data Division 
clauses, Procedure Division statements, and 
Compiler-Directing statements. 

ILE Concepts, SC41-5606-06, explains concepts 
and terminology pertaining to the Integrated 
Language Environment architecture of the 
OS/400 licensed program. Topics covered 


include creating modules, binding, running 
programs, debugging programs, and handling 
exceptions. 


WebSphere Development Studio: ILE RPG 
Programmer's Guide, SC09-2507-04, provides 
information about the ILE RPG programming 
language, which is an implementation of the 
RPG IV language in the Integrated Language 
Environment (ILE) on the iSeries system. It 
includes information on creating and running 
programs, with considerations for procedure 
calls and interlanguage programming. The 
guide also covers debugging and exception 
handling and explains how to use iSeries files 
and devices in RPG programs. Appendixes 
include information on migration to RPG IV 
and sample compiler listings. It is intended for 
people with a basic understanding of data 
processing concepts and of the RPG language. 


WebSphere Development Studio: ILE RPG 
Reference, SC09-2508-04, provides information 
about the ILE RPG programming language. 
This manual describes, position by position and 
keyword by keyword, the valid entries for all 
RPG IV specifications, and provides a detailed 
description of all the operation codes and 
built-in functions. This manual also contains 
information on the RPG logic cycle, arrays and 
tables, editing functions, and indicators. 


WebSphere Development Studio: ILE RPG 
Reference Summary, SX09-1315-03, provides 
information about the RPG III and RPG IV 
programming language. This manual contains 
tables and lists for all specifications and 
operations in both languages. A key is provided 
to map RPG III specifications and operations to 
RPG IV specifications and operations. 
Local Device Configuration, SC41-5121-00, 
provides information about configuring local 
devices on the iSeries system. This includes 
information on how to configure the following: 
- Local work station controllers (including 
twinaxial controllers) 
— Tape controllers 
— Locally attached devices (including twinaxial 
devices) 
Machine Interface Functional Reference, 
SC41-5810-00, describes the machine interface 
instruction set. Describes the functions that can 
be performed by each instruction and also the 
necessary information to code each instruction. 
Printer Device Programming, SC41-5713-05, 
provides information to help you understand 
and control printing. Provides specific 
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information on printing elements and concepts 
of the iSeries system, printer file and print 
spooling support for printing operations, and 
printer connectivity. Includes considerations for 
using personal computers, other printing 
functions such as Business Graphics Utility 
(BGU), advanced function printing (AFP), and 
examples of working with the iSeries system 
printing elements such as how to move spooled 
output files from one output queue to a 
different output queue. Also includes an 
appendix of control language (CL) commands 
used to manage printing workload. Fonts 
available for use with the iSeries system are 
also provided. Font substitution tables provide 
a cross-reference of substituted fonts if attached 
printers do not support application-specified 
fonts. 


REXX/400 Programmer’s Guide, SC41-5728-00, 
provides a wide-ranging discussion of 
programming with REXX on the AS/400 
system. Its primary purpose is to provide 
useful programming information and examples 
to those who are new to Procedures Language 
400/REXX and to provide those who have used 
REXX in other computing environments with 
information about the Procedures Language 
400/REXX implementation. 


WebSphere Development Studio: ILE RPG 
Programmer's Guide, SCO09-2507-04, provides 
information needed to design, code, compile, 
and test RPG programs on the AS/400 system. 
The manual provides information on data 
structures, data formats, file processing, 
multiple file processing, the automatic report 
function, RPG command statements, testing 
and debugging functions, application design 
techniques, problem analysis, and compiler 
service information. The differences between 
the RPG for iSeries compiler, the System/38° 
environment RPG III compiler, and the 
System/36°-compatible RPG II compiler are 
also discussed. 

The Basic Securityl topic explains why security 
is necessary, defines major concepts, and 
provides information on planning, 
implementing, and monitoring basic security on 
the iSeries system. 


iSeries Security Reference, SC41-5302-06, tells 
how system security support can be used to 
protect the system and the data from being 
used by people who do not have the proper 
authorization, protect the data from intentional 
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or unintentional damage or destruction, keep 
security information up-to-date, and set up 
security on the system. 


Local Device Configuration, SC41-5121-00, 
provides step-by-step procedures for initial 
installation, installing licensed programs, 
program temporary fixes (PTFs), and secondary 
languages from IBM. This manual is also for 
users who already have an iSeries system with 
an installed release and want to install a new 
release. 


System API Programming, SC41-5800-00, 
provides information for the experienced 
application and system programmers who want 
to use the OS/400 application programming 
interfaces (APIs). Provides getting started and 
examples to help the programmer use APIs. 
The ystem API Referencel topic provides 
information for the experienced programmer on 
how to use the application programming 
interfaces (APIs) to such OS/400 functions as: 
— Dynamic Screen Manager 

— Files (database, spooled, hierarchical) 

— Message handling 

— National language support 

— Network management 

— Objects 

— Problem management 

— Registration facility 

— Security 

— Software products 

— Source debug 

— UNIX-type 

— User-defined communications 

— User interface 


— Work management 


Includes original program model (OPM), 
Integrated Language Environment (ILE), and 
UNIX-type APIs. 

The Kystems Management topic provides 
information about the system unit control 
panel, starting and stopping the system, using 
tapes and diskettes, working with program 
temporary fixes, as well as handling problems. 


Tape and Diskette Device Programming, 
SC41-5716-02, provides information to help 
users develop and support programs that use 
tape and diskette drives for I/O. Includes 
information on device files and descriptions for 
tape and diskette devices. 
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__EXBDY built-in 6 
__VBDY built-in 6 
_C_Get_Ssn_Handle() function 55 
_C_TS_malloc 171, 490 
_C_TS_malloc_debug 490 
_C_TS_malloc_info 490 
_C_TS_malloc64 171, 490 
_EXBDY macro 6 
_fputchar() function 102 
_gcevt() function 132 
_GetExcData() function 135 
_INTRPT_Hndlr_Parms_T 4 
_itoa() function 154 
_ltoa() function 167 
_Racquire() function 228 
_Rclose() function 229 
_Rcommit() function 230 
_Rdelete() function 232 
_Rdevatr() function 233 
_Rfeod() function 246 
_Rfeov() function 247 
_Rformat() function 249 
_Rindara() function 251 
_Riofbk() function 252 
_Rlocate() function 254 
_Ropen() function 257 
_Ropnfbk() function 261 
_Rpgmdev() function 262 
_Rreadd() function 263 
_Rreadf() function 265 
_Rreadindv() function 267 
_Rreadk() function 270 
_Rreadl() function 274 
_Rreadn() function 275 
_Rreadnc() function 278 
_Rreadp() function 279 
_Rreads() function 282 
_Rrelease() function 283 
_Rrlslck() function 285 
_Rrollbck() function 286 
_Rupdate() function 288 
_Rupfb() function 290 
_Rwrite() function 291 
_Rwrited() function 293 
_Rwriterd() function 296 
_Rwrread() function 297 
_ultoa() function 380 
_VBDY macro 6 
_wcsicmp() function 413 
_wesnicmp() function 415 
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abnormal program end 37 
abort() function 37 
abs() function 38 
absolute value 
abs() function 38 
fabs 74 
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absolute value (continued) 
labs 155 
access mode 76, 92 
acos() function 39 
acquire a program device 228 
adding data to streams 76 
append mode 
using fopen() function 92 
appending data to files 76 
arccosine 39 
arcsine 43 
arctangent 45 
argument list functions 31 
asctime() function 40 
asctime_r() function 42 
asin() function 43 
assert() function 44 
assert.h include file 3 
atan() function 45 
atan2() function 45 
atexit() function 46 
atof() function 47 
atoi() function 49 
atol() function 50 
atoll() function 
strings to long long values 50 


bessel functions 23, 51 
binary files 94 
binary search 52 
blksize 94 
block size 94 
bsearch() function 52 
btowc() function 54 
buffers 
assigning 305 
comparing 188 
copying 189, 191 
flushing 80 
searching 187 
setting characters 192 
bufsiz constant 15 
builtins 
__EXBDY 6 
__VBDY 6 
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calculating 
absolute value 38 
absolute value of long integer 
arccosine 39 
arctangent 45 
base 10 logarithm 166 
cosine 64 
error functions 72 
exponential function 73 
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floating-point absolute value 74 


calculating (continued) 
floating-point remainder 91 
hyperbolic cosine 65 
hyperbolic sine 316 
hypotenuse 145 
logarithm 165 
natural logarithm 165 
quotient and remainder 70 
sine 315 
time difference 69 
calloc() function 56 
cancel handler reason codes 459 
case mapping functions 35 
catclose() function 57 
catgets() function 58 
catopen() function 59 
ceil() function 61 
ceiling function 61 
changing 
data area 218 
environment variables 211 
file position 114 
reserved storage block size 234 
character 
converting 
to floating-point 50 
to integer 49 
to long integer 50 
reading 82, 133 
setting 192 
ungetting 381 
writing 101, 210 
character case mapping 
tolower 377 
toupper 377 
towlower 379 
towupper 379 
character testing 
ASCII value 146 
character property 149, 152 
isalnum 147 
isalpha 147 
iscntrl 147 
isdigit 147 
isgraph 147 
islower 147 
isprint 147 
ispunct 147 
isspace 147 
isupper 147 
isxdigit 147 
wide alphabetic character 150 
wide alphanumeric character 150 
wide control character 150 
wide decimal-digit character 150 
wide hexadecimal digit 150 
wide lowercase character 150 
wide non-alphanumeric 
character 150 
wide non-space character 150 
wide printing character 150 
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character testing (continued) 
wide uppercase character 150 
wide whitespace character 150 
character testing functions 34 
clear error indicators 62 
clearerr 62 
clock() function 63 
CLOCKS_PER_SEC 63 
closing 
file 229 
message catalog 57 
stream 75 
comparing 
buffers 188 
strings 326, 329, 331, 344 
comparing strings 323, 341 
compile regular expression 237 
concatenating strings 324, 343 
conversion functions 
QXXDTOP 219 
QXXDTOZ 220 
QXXITOP() 221 
QXXITOZ 221 
QXXPTOD 222 
QXXPTOI 223 
QXXZTOD 224 
QXXZTOI 225 
converting 
character case 377 
character string to double 357 
character string to long integer 362 
date 350 
double to zoned decimal 220 
floating-point numbers to integers and 
fractions 195 
floating point to packed decimal 219 
from structure to string 40 
from structure to string (restartable 
version) 42 
integer to a character in the ASCII 
charactger set 376 
integer to packed decimal 221 
integer to zoned decimal 221 
local time 193 
monetary value to string 334 
multibyte character to a wide 
character 176 
multibyte character to wchar_t 186 
multibyte string to a wide character 
string 180 
packed decimal to double 222 
packed decimal to integer 223 
single byte to wide character 54 
sting to formatted date and time 407 
string segment to unsigned 
integer 364 
strings to floating-point values 47 
strings to integer values 49 
strings to long values 50 
time 141, 143, 163, 164, 350 
time to character string 66, 67 
wide character case 379 
wide-character string to double 422 
wide character string to multibyte 
string 418 
wide character to a multibyte 
character 396 


converting (continued) 
wide character to byte 435 
wide character to long integer 424 
wide character to multibyte 
character 436 
wide-characterc string to unsigned 
long 430 
zoned decimal to double 224 
zoned decimal to integer 225 
copying 
bytes 189, 191 
strings 330, 346 
cos() function 64 
cosh() function 65 
creating 
a temporary file 374, 375 
ctime() function 66 
ctime_r() function 67 
ctype functions 147 
ctype.h include file 3 
currency functions 24 


D 


data conversion 
atof() function 47 
atoi() function 49 
atol() function 50 
data items 108 
data type compatibility 
CL 465, 467, 468 
COBOL 466 
ILE COBOL 463 
RPG 462, 465 
data type limits 7 
date and time conversion 350 
decimal.h include file 4 
deleting 
file 243 
record 232, 243 
determine the display width of a wide 
character 441 
determining 
display width of a wide character 
string 433 
display width of a wide-character 
string 434 
length of a multibyte character 173 
differential equations 23 
difftime() function 69 
divf() function 70 
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end-of-file indicator 62, 79 
ending a program 37, 73 
environment 
functions 32 
interaction 32 
retrieving information 158 
table 135 
variables 135, 211 
environment variables 
adding 211 
changing 211 
searching 135 
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eofile 

clearing 245 

macro 15 

resetting error indicator 62 
erf() function 72 
erfc() function 72 
errno 4 
errno.h include file 4 
errno macros 451 
errno values for Integrated File 
System 453 
errno variable 198 
error handling 

assert 44 

clearerr 62 

ferror 79 

functions 21 

perror 198 

stream I/O 79 

strerror 333 
error indicator 79 
error macros, mapping stream I/O 
exceptions 455 
error messages 

printing 198 
except.h include file 4 
exception class 

listing 461 

mapping 458 
exit() function 73 
EXIT_FAILURE 16, 73 
EXIT_SUCCESS 16, 73 
exp() function 73 
exponential functions 

exp 73 

frexp 112 

Idexp 156 

log 165 

log10 166 

pow 199 

sqrt 318 


F 


fabs() function 74 
fclose() function 75 
fdopen() function 76 
feof() function 79 
ferror() function 79 
fflush() function 80 
fgetc() function 82 
fgetpos() function 84 
fgets() function 85 
fgetwc() function 86 
fgetws() function 88 
file 
appending to 76 
handle 90 
include 3 
maximum opened 15 
name length 15 
positioning 245 
renaming 244 
updating 76 
file errors 62 
file handling 
remove 243 


file handling (continued) 

rename 244 

tmpnam 375 
filename length 15 
file names, temporary 15 
file positioning 84, 114, 117, 118 
FILE type 15 
fileno() function 90 
float.h include file 7 
floor() function 91 
flushing buffers 80 
fmod() function 91 
fopen() function 92 
fopen, maximum simultaneous files 15 
format data as wide characters 123 
formatted I/O 99 
fpos_t 16 
fprintf() function 99 
fputc() function 101 
fputs() function 103 
fputwe() function 104 
fputws() function 106 
fread() function 108 
free() function 109 
freopen() function 111 
frexp() function 112 
fscanf() function 113 
fseek() function 114 
fseeko() function 114 
fsetpos() function 117 
ftell() function 118 
fwide() function 120 
fwprintf() function 123 
fwrite() function 127 
fwscanf() function 128 


G 


gamma() function 131 
getc() function 133 
getchar() function 133 
getenv() function 135 
gets() function 137 
getting 
handle for character mapping 437 
handle for character property 
classification 438 
wide character from stdin 140 
getwc() function 138 
getwchar() function 140 
gmtime() function 141 
gmtime_r() function 143 
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handling interrupt signals 313 
HUGE_VAL 8 

hypot() function 145 
hypotenuse 145 


I/O errors 62 

idate 
correcting for local time 163, 164 
functions 24 


include files 

assert.h 3 

ctypeh 3 

decimal.h 4 

errno.h 4 

except.h 4 

floath 7 

limits.h 7 

locale.h 7 

mathh 8 

pointerh 9 

recio.h 9 

regex.h 13 

settmp.h 13 

signalh 14 

stdarg.h 14 

stddef.h 14 

stdio.h 15 

stdlibh 16 

string.h 17 

time.h 17 

westr.h 18 

xxevth 18 

xxdtaah 19 

xxenv.h 19 

xxfdbk.h 19 
indicators, error 62 
initial strings 346 
integer 

pseudo-random 227 
Integrated File System errno values 453 
internationalization 7 
interrupt signal 313 
invariant character 

hexadecimal representation 469 
isalnum() function 147 
isalpha()function 147 
isascii() function 146 
isblank() function 149 
iscntrl() function 147 
isdigit() function 147 
isgraph() function 147 
islower() function 147 
isprint() function 147 
ispunct() function 147 
isspace()function 147 
isupper() function 147 
iswalnu() function 150 
iswentrl() function 150 
iswctype() function 152 
iswdigit() function 150 
iswgraph() function 150 
iswlower() function 150 
iswprint() function 150 
iswpunct() function 150 
iswspace() function 150 
iswupper() function 150 
iswxdigit() function 150 
isxdigit() function 147 
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labs() function 155 
langinfo.h include file 7 
language collation string 
comparison 404 
Idexp() function 156 


Idiv() function 156 
length function 341 
length of variables 462 
library functions 
absolute value 


abs 38 
fabs 74 
labs 155 


character case mapping 
tolower 377 
toupper 377 
towlower 379 
towupper 379 
character testing 
isalnum 147 
isalpha 147 
isascii 146 
iscntrl 147 
isdigit 147 
isgraph 147 
islower 147 
isprint 147 
ispunct 147 
isspace 147 
isupper 147 
iswalnum 150 
iswalpha 150 
iswentrl 150 
iswctype 152 
iswdigit 150 
iswgraph 150 
iswlower 150 
iswprint 150 
iswpunct 150 
iswspace 150 
iswupper 150 
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isxdigit 147 
conversion 
QXXDTOP 219 
QXXDTOZ 220 
QXXITOP 221 
QXXITOZ 221 
QXXPTOD 222 
QXXPTOI 223 
QXXZTOD 224 
QXXZTOI 225 
strfmon 334 
strptime 350 
wesftime 407 
data areas 
QXXCHGDA 218 
QXXRTVDA = 223 
error handling 
_GetExcData 135 
clearerr 62 
raise 226 
strerror 333 
exponential 
exp 73 
frexp 112 
Idexp 156 
log 165 
log10 166 
pow 199 
file handling 
fileno 90 
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library functions (continued) 
file handling (continued) 


library functions (continued) 
multibyte 


library functions (continued) 
stream input/output (continued) 


remove 243 _wesicmp 413 fscanf 113 
rename 244 _wesnicmp 415 fseek 114 
tmpfile 374 btowc 54 fsetpos 117 
tmpnam 375 mblen 172 ftell 118 
locale mbrlen 173 fwide 120 
localeconv 158 mbrtowc 176 fwprintf 123 
nllanginfo 196 mbsinit 179 fwrite 127 
setlocale 308 mbsrtowcs 180 fwscanf 128 
strxfrm 366 mbstowcs 182 gete 133 
math mbtowc 186 getchar 133 
acos 39 towctrans 378 gets 137 
asin 43 wertomb 396 getwc 138 
atan 45 wescat 400 getwchar 140 
atan2 45 weschr 402 printf 200 
bessel 51 wescmp 403 pute 210 
ceil 61 wescoll 404 putchar 210 
cos 64 wescpy 405 puts 212 
cosh 65 wescspn 406 putwe 213 
div 70 weslen 409 putwchar 214 
erf 72 wesncat 410 scanf 299 
erfe 72 wesnemp 411 setbuf 305 
floor 91 wesncpy 413 setvbuf 311 
fmod 91 wespbrk 416 sprintf 317 
frexp 112 wesrchr 417 sscanf 322 
gamma 131 wesrtombs 418 swprintf 367 
hypot 145 wesspn 420 swscanf 369 
Idiv 156 westombs 426 ungetc 381 
log 165 weswes 432 ungetwe 382 
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